Webhooks einrichten: Ereignisse sicher empfangen

Ein Webhook-Abo schickt Ereignisse aus OneSign (zum Beispiel „Vorgang abgeschlossen“) per HTTP-POST an eine Adresse Ihres Systems. So müssen Sie nicht ständig nachfragen. Jedes Abo hat ein eigenes Secret, mit dem Sie die Herkunft jeder Zustellung prüfen.

Abo anlegen

1. Öffnen Sie im Dashboard „Entwickler → Webhooks“ und wählen Sie „Abo anlegen“. Inhaber und Admins legen Abos an, Betrachter sehen sie nur. Über die API geht dasselbe mit einem Schlüssel, der den Scope webhooks:manage hat.
2. Tragen Sie die Zieladresse ein: nur https, öffentlich erreichbar, Port 443 oder 8443. Das gilt auch im Testmodus; für lokale Tests brauchen Sie eine öffentliche https-Adresse, etwa über einen Tunnel.
3. Wählen Sie die Ereignisse: einzelne Namen wie envelope.completed, eine ganze Familie wie recipient.* oder alle Ereignisse, die der Schlüssel lesen darf.
4. Speichern Sie das Secret sofort an einem sicheren Ort. Es wird genau einmal angezeigt; später können Sie nur ein neues erzeugen („Secret erneuern“, mit wählbarer Übergangszeit für das alte).
5. Senden Sie über „Test senden“ ein Beispiel-Ereignis. Es trägt „test: true“, damit Ihr System es erkennt.

Per API legt ein Test-Schlüssel ein Abo für Test-Ereignisse an, ein Live-Schlüssel eines für Live-Ereignisse. Je Modus sind bis zu 25 Abos möglich.

Signatur prüfen

Jede Zustellung trägt zwei Sätze von Signatur-Headern über denselben Roh-Body. Es genügt, einen davon zu prüfen: webhook-id, webhook-timestamp und webhook-signature (Standard Webhooks) oder X-QGW-Signature.

• Prüfen Sie gegen den Roh-Body, also die empfangenen Bytes, bevor JSON geparst wird.
• Lehnen Sie Zeitstempel ab, die älter als fünf Minuten sind, und vergleichen Sie in konstanter Zeit.
• Während einer Secret-Erneuerung trägt jeder Header einen Wert je gültigem Secret. Akzeptieren Sie die Anfrage, wenn einer passt.

Genau einmal verarbeiten

• Mindestens einmal: Dasselbe Ereignis kann mehrfach ankommen. Speichern Sie die Ereignis-ID (webhook-id) und ignorieren Sie Wiederholungen.
• Keine garantierte Reihenfolge: Entscheiden Sie anhand von createdAt oder dem Status im Objekt, oder lesen Sie das Objekt per GET nach.
• Schnell antworten: Erfolg ist jede 2xx-Antwort innerhalb von 10 Sekunden. Erledigen Sie die Arbeit im Hintergrund.
• Unbekannte Ereignisse mit 2xx beantworten: Es kommen neue Ereignisnamen hinzu.

Wiederholungen und Zustellprotokoll

• Jede andere Antwort, ein Timeout oder ein Netzwerkfehler löst weitere Versuche aus: nach etwa 1, 5, 15 und 60 Minuten, 3 und 6 Stunden, danach alle 12 Stunden, bis 72 Stunden nach dem Ereignis (jeweils zu einem zufälligen Zeitpunkt in der zweiten Hälfte des Schritts). Weiterleitungen (3xx) werden nicht verfolgt und zählen als Fehler.
• Antwortet Ihr Server mit 410, endet die Zustellung und das Abo wird deaktiviert. Nach zehn endgültig gescheiterten Zustellungen in Folge über mindestens 24 Stunden wird das Abo pausiert; Sie setzen es mit „Fortsetzen“ fort.
• Im Abo sehen Sie das Zustellprotokoll und können einzelne Zustellungen neu senden. Was Ihr Endpunkt verpasst hat, steht 30 Tage lang im Ereignisprotokoll (Entwickler → Ereignisse bzw. GET /v1/events).