Webhooks

Passez callback_url dans POST /edits. Quand la tâche atteint succeeded ou failed, nous envoyons en POST à cette URL le même JSON que celui renvoyé par GET /edits/{id}.

• callback_url doit être une URL https. Sa chaîne de requête est conservée : vous pouvez ajouter votre propre référence, comme https://example.com/hooks/rewords?order=1234.
• Répondez avec n’importe quel statut 2xx dans les 10 secondes pour en accuser réception. Tout le reste — un autre statut, un délai dépassé, une erreur de connexion — compte comme un échec.
• Une livraison échouée est retentée 1, 5 et 30 minutes après la tentative précédente : la dernière arrive environ 36 minutes après la première. Ensuite nous arrêtons ; GET /edits/{id} renvoie toujours le résultat.
• Chaque nouvelle tentative envoie les mêmes octets avec la même signature. À cause des nouvelles tentatives, vous pouvez recevoir la même tâche plusieurs fois : utilisez l’id de la modification pour ignorer celle que vous avez déjà traitée.
• Chaque livraison est signée : X-Rewords-Signature: sha256=<64 caractères hexadécimaux>, un HMAC-SHA256 du corps brut de la requête avec votre secret de webhook. Utilisez la chaîne entière du secret, préfixe whsec_ compris, comme clé HMAC.

Votre secret de webhookCopy Anchor Link

Il y a un secret de webhook par compte, partagé par toutes ses clés. Vous le trouverez sur votre page des clés d’API. Vous pouvez l’y réinitialiser ; l’ancien secret cesse aussitôt de fonctionner, alors mettez à jour votre récepteur juste après.

Vérifier la signatureCopy Anchor Link

Rejetez la requête avec 401 si la vérification échoue, et ne la traitez pas. Un nouvel envoi ne peut pas corriger une mauvaise signature.

import crypto from 'node:crypto';

export function verify(rawBody, header, secret) {
  if (typeof header !== 'string') return false;
  const expected = Buffer.from('sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex'));
  const received = Buffer.from(header);
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

import hashlib, hmac
from typing import Optional

def verify(raw_body: bytes, header: Optional[str], secret: str) -> bool:
    if not header:
        return False
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(header.encode(), expected.encode())

Vérifiez à partir des octets bruts avant d’analyser le JSON — le resérialiser change la signature. Dans Express, par exemple, lisez le corps avec express.raw({ type: 'application/json' }).