Webhooks
Charge utile, signature HMAC, protection anti-rejeu et nouvelles tentatives.
Lorsque callBackUrl est fourni à createTask, une livraison est mise en file dès que la tâche devient terminale. Il n’existe pas de notification intermédiaire queued → running. Lors d’une nouvelle livraison v2, request_id et les données métier restent identiques ; seuls url et expiresAt sont renouvelés. Vérifiez la signature sur le corps reçu et dédupliquez avec request_id.
signature = base64(
HMAC-SHA256(
secret,
"<task_id>.<timestamp>.<sha256_hex(raw_body)>"
)
)Vérifier la signature
X-Webhook-Signature est un HMAC-SHA256 encodé en Base64 sur <task_id>.<timestamp>.<sha256_hex(raw_body)>. task_id vient de data.taskId. Hachez les octets bruts reçus sans désérialiser puis resérialiser le JSON.
Refusez un X-Webhook-Timestamp hors de votre fenêtre, même si la signature est correcte. Comparez en temps constant et configurez un webhook secret non vide.
Tolérer les doublons
request_id identifie la livraison et reste stable lors des nouvelles tentatives. Placez une contrainte unique en base et répondez 2xx si l’événement a déjà été traité. Acquittez rapidement puis travaillez depuis votre file interne.
body.code vaut 200 même pour une tâche failed. Décidez du succès uniquement avec data.state.
Consultez le contrat OpenAPI 3.1 pour la définition complète des champs.