Webhook
Формат события, HMAC-подпись, защита от replay и повторы доставки.
Если в createTask указан callBackUrl, доставка ставится в очередь после перехода задачи в конечное состояние. Промежуточного события queued → running нет. Повторная доставка v2 сохраняет request_id и данные события, обновляя только url и expiresAt. Проверяйте подпись по полученному телу запроса и устраняйте дубликаты по request_id.
signature = base64(
HMAC-SHA256(
secret,
"<task_id>.<timestamp>.<sha256_hex(raw_body)>"
)
)Проверка подписи
X-Webhook-Signature — это Base64 от HMAC-SHA256 для строки <task_id>.<timestamp>.<sha256_hex(raw_body)>. task_id берется из data.taskId. Хэшируйте исходные байты запроса, не сериализуйте JSON повторно.
Отклоняйте X-Webhook-Timestamp вне допустимого окна даже при правильной подписи. Сравнивайте за постоянное время и задайте непустой webhook secret.
Повторные доставки
request_id идентифицирует доставку и не меняется при повторах. Создайте уникальное ограничение в базе и отвечайте 2xx, если событие уже обработано. Сначала подтвердите прием, затем обрабатывайте через внутреннюю очередь.
body.code равен 200 даже для failed. Успех определяется только по data.state.
Полные определения полей приведены в контракте OpenAPI 3.1.