Webhooks
Payload, HMAC-Signatur, Replay-Schutz und erneute Zustellung.
Mit callBackUrl in createTask wird eine Zustellung eingeplant, sobald der Task einen terminalen Status erreicht. Für queued → running gibt es keine Zwischenmeldung. Bei v2-Wiederholungen bleiben request_id und Ereignisdaten gleich; nur url und expiresAt werden erneuert. Prüfen Sie die Signatur über den tatsächlich empfangenen Body und deduplizieren Sie anhand von request_id.
signature = base64(
HMAC-SHA256(
secret,
"<task_id>.<timestamp>.<sha256_hex(raw_body)>"
)
)Signatur prüfen
X-Webhook-Signature ist Base64-codiertes HMAC-SHA256 über <task_id>.<timestamp>.<sha256_hex(raw_body)>. task_id stammt aus data.taskId. Hashen Sie die empfangenen Rohbytes und serialisieren Sie JSON nicht erneut.
Lehnen Sie X-Webhook-Timestamp außerhalb Ihres Toleranzfensters auch bei gültiger Signatur ab. Vergleichen Sie in konstanter Zeit und setzen Sie ein nicht leeres webhook secret.
Mehrfachzustellung beherrschen
request_id ist die Zustellungs-ID und bleibt bei Wiederholungen gleich. Sichern Sie sie mit einem Unique Constraint und antworten Sie bei bereits verarbeiteten Ereignissen mit 2xx. Bestätigen Sie zuerst und arbeiten Sie danach aus Ihrer Queue.
Auch fehlgeschlagene Tasks haben body.code: 200. Prüfen Sie immer data.state.
Die vollständigen Felddefinitionen stehen im OpenAPI-3.1-Vertrag.