Projekte und Phasen

Webhook-Referenz: Ereignisse, Header, Signatur und Wiederholungen

Der Vertrag jeder Zustellung: Ereignisse des Katalogs, x-aproova-*-Header, Prüfung der Signatur und wann Aproova erneut sendet.

Für wen geeignetEigentümerAdministratoren

Geprüft am 14. November 2026

Bevor Sie beginnen

Ein unter Einstellungen > Integrationen angelegter Webhook (Workspace-Inhaber, Flow oder höher) und das im Formular angezeigte Signaturgeheimnis.

Kurzer Aufgabenüberblick

Beginnen Sie mit diesen Schritten. Weitere Schritte folgen direkt darunter.

Schritt 1
Ereignisse des Katalogs: review.created (Prüfung erstellt), review.version_uploaded (Version hochgeladen), review.comment_created (Kommentar erstellt), review.verdict_submitted (Entscheidung eines Teilnehmers), review.approved (Prüfung freigegeben), review.rejected (Prüfung abgelehnt), review.changes_requested (Änderungen angefordert), review.approval_reopened (Freigabe wieder geöffnet), review.unlocked (Prüfung entsperrt). Freigabe wieder geöffnet und Prüfung entsperrt erhalten nur Webhooks, die diese Ereignisse auswählen; bestehende Abonnements erhalten weiterhin nur ihre bisherigen Ereignisse. Die Schaltfläche Testen sendet das Ereignis webhook.test.
Schritt 2
Header jeder Zustellung: x-aproova-event (Ereignistyp), x-aproova-delivery (Zustellungs-ID), x-aproova-timestamp (Sekunden seit 1970, UTC) und x-aproova-signature. Außerdem werden user-agent Aproova-Webhooks/1.0 und, wenn ein Inhalt vorhanden ist, content-type application/json gesendet. Eigene Header ersetzen diese Namen nicht.
Schritt 3
Signatur: x-aproova-signature = „sha256=“ gefolgt vom hexadezimalen HMAC-SHA256, berechnet mit dem Webhook-Geheimnis über den Text „${timestamp}.${body}“; timestamp ist der Wert von x-aproova-timestamp, body der unveränderte empfangene Inhalt (leerer Text bei GET, DELETE oder ohne Inhalt). Berechnen Sie sie über die empfangenen Bytes, bevor Sie das JSON parsen, und vergleichen Sie in konstanter Zeit.

4Standardinhalt (JSON): event, event_id, created_at, workspace_id, locale und, falls vorhanden, proof, version, folder, teams, comment, decision, actor und whatsapp. Leere Felder werden weggelassen. Der Text interner Kommentare wird nie gesendet.
5Optionale Entscheidungsfelder: verification_method (authenticated_user, email_otp oder declared) und actor_verified (true nur bei authenticated_user und email_otp). Sie erscheinen nur bei Entscheidungsereignissen mit diesem Nachweis; in einem eigenen Inhalt nutzen Sie {{data.verification_method}} und {{data.actor_verified}}.
6Antwort: Jeder 2xx-Status gilt als zugestellt. Aproova wartet bis zu 6 Sekunden auf eine Antwort.
7Wiederholungen: Netzwerkfehler, Zeitüberschreitungen und die Status 408, 425, 429 und 5xx werden wiederholt, andere 4xx nicht. Es gibt höchstens 4 Versuche: den 2. etwa 5 Minuten nach dem 1. Fehler, den 3. etwa 30 Minuten danach und den 4. etwa 120 Minuten danach. Nach dem 4. gilt die Zustellung im Verlauf als endgültig fehlgeschlagen.
8Jede Wiederholung verwendet dieselbe event_id und denselben x-aproova-delivery. Nutzen Sie diesen Wert, um Wiederholungen am Ziel zu ignorieren. Hat der Workspace keinen Tarif mit Webhooks mehr, schlägt die Zustellung ohne Wiederholung fehl.

Ihr Dienst prüft die Signatur, erkennt Wiederholungen an der event_id und antwortet schnell mit 2xx.

Signatur stimmt nicht: Berechnen Sie sie über den unveränderten Inhalt, ohne das JSON neu zu formatieren, mit dem aktuellen Geheimnis (ein neues Geheimnis macht das alte ungültig).
Doppelte Aktion am Ziel: Eine langsame Antwort oder ein 5xx löst eine Wiederholung aus. Speichern Sie die bereits verarbeitete event_id.
Ein neues Ereignis kommt nicht an: Wählen Sie Freigabe wieder geöffnet oder Prüfung entsperrt in der Ereignisliste des Webhooks aus.