Webhooks
Cuerpo, firma HMAC, protección contra repetición y reenvíos.
Si incluyes callBackUrl en createTask, se encola una entrega cuando la tarea alcanza un estado terminal. No hay notificación intermedia queued → running. Los reenvíos v2 conservan request_id y los datos del evento; solo renuevan url y expiresAt. Verifica la firma del cuerpo recibido y elimina duplicados mediante request_id.
signature = base64(
HMAC-SHA256(
secret,
"<task_id>.<timestamp>.<sha256_hex(raw_body)>"
)
)Verificar la firma
X-Webhook-Signature es HMAC-SHA256 codificado en Base64 sobre <task_id>.<timestamp>.<sha256_hex(raw_body)>. task_id procede de data.taskId. Calcula el hash sobre los bytes sin volver a serializar el JSON.
Rechaza X-Webhook-Timestamp fuera de tu ventana aunque la firma sea válida. Compara en tiempo constante y configura un webhook secret no vacío.
Aceptar duplicados
request_id identifica la entrega y no cambia en los reintentos. Aplica una restricción única en tu base de datos y responde 2xx si ya se procesó. Confirma primero y trabaja después desde tu cola interna.
body.code vale 200 incluso si la tarea está failed. Decide el éxito con data.state.
Consulta el contrato OpenAPI 3.1 para ver la definición completa de los campos.