Webhooks
Payload, assinatura HMAC, proteção contra replay e reentrega.
Ao fornecer callBackUrl em createTask, uma entrega entra na fila quando a tarefa atinge um estado terminal. Não existe notificação intermediária queued → running. Reenvios v2 mantêm request_id e os dados do evento; apenas url e expiresAt são renovados. Verifique a assinatura do corpo recebido e elimine duplicatas por request_id.
signature = base64(
HMAC-SHA256(
secret,
"<task_id>.<timestamp>.<sha256_hex(raw_body)>"
)
)Verifique a assinatura
X-Webhook-Signature é HMAC-SHA256 em Base64 sobre <task_id>.<timestamp>.<sha256_hex(raw_body)>. task_id vem de data.taskId. Calcule o hash dos bytes brutos recebidos sem serializar o JSON novamente.
Recuse X-Webhook-Timestamp fora da janela, mesmo com assinatura válida. Compare em tempo constante e configure um webhook secret não vazio.
Aceite duplicatas
request_id identifica a entrega e não muda nas novas tentativas. Crie uma restrição única no banco e responda 2xx quando já tiver processado. Confirme primeiro e trabalhe depois pela sua fila interna.
body.code é 200 mesmo quando a tarefa está failed. Decida o sucesso com data.state.
Consulte o contrato OpenAPI 3.1 para ver a definição completa dos campos.