Webhooks empfangen

Ein Webhook bedeutet, dass AssinaJá bei Ihrem System anklopft, wenn mit einem Dokument etwas passiert, statt dass Ihr System ständig nachfragt. Es ist eine POST-Anfrage, die die Plattform an eine Adresse von Ihnen sendet.

Diese Seite richtet sich an alle, die AssinaJá mit einem anderen Programm integrieren. Wenn Sie nur sehen möchten, was mit einem Dokument geschehen ist, verwenden Sie den Verlauf des Dokuments.

Die Adresse einrichten

Die Webhooks der Organisation werden unter Einstellungen → Entwickler → Webhooks eingerichtet, und nur der Inhaber der Organisation hat Zugriff auf diese Registerkarte. Die Seite hat drei Teile: Endpunkt und Ereignisse, Webhook-Secret und darunter Zustellungen.

Unter Endpunkt und Ereignisse:

1. Geben Sie unter Webhook-URL die Adresse Ihres Systems ein — “HTTPS, Port 443 oder 8443, unter einer öffentlichen Adresse. Interne Namen und private Adressen werden abgelehnt.”
2. Wählen Sie unter Zu empfangende Ereignisse die Ereignisse — siehe Die Ereignisse. “Ohne ausgewählte Ereignisse wird nichts gesendet. Wählen Sie mindestens eines aus.”
3. Prüfen Sie, ob Versand aktiv eingeschaltet ist, und klicken Sie auf Speichern.

Testereignis senden schickt eine Anfrage an die Adresse und sagt, was sie geantwortet hat — “Der Endpunkt hat mit {Code} geantwortet.” oder “Der Testversand ist fehlgeschlagen: {Fehler}”.

Die Adresse, die die Plattform akzeptiert

Die Adresse ist nicht frei wählbar. Die Plattform prüft sie vor dem Speichern, damit sie nicht dazu missbraucht werden kann, Rechner anzusprechen, die nicht Ihnen gehören:

• HTTPS, immer.
• Port 443 oder 8443, kein anderer.
• Ein öffentlicher Host: weder localhost noch *.localhost, *.internal oder metadata.google.internal.
• Eine öffentliche Adresse. Löst der Name zu einer privaten oder reservierten Adresse auf — 10.x, 172.16–31.x, 192.168.x, 127.x, 169.254.x, 100.64.x, Multicast oder die Entsprechungen in IPv6 —, wird er abgelehnt. Alle Adressen, zu denen der Name auflöst, werden geprüft, nicht nur die erste.

Die Ablehnung erscheint in Ihrer Sprache:

Ablehnung	Was zu tun ist
“Geben Sie die Webhook-URL an.”	das Feld ist leer
“Die Adresse ist keine gültige URL.”	das Schema fehlt oder es gibt einen Tippfehler
“Die Adresse muss HTTPS verwenden.”	ersetzen Sie http:// durch https://
“Der Port muss 443 oder 8443 sein.”	entfernen Sie den Port aus der Adresse oder verwenden Sie einen dieser
“Der Host ist reserviert (localhost, .internal, Cloud-Metadaten) und kann keine Webhooks empfangen.”	verwenden Sie einen aus dem Internet erreichbaren Namen
“Die IP-Adresse ist nicht öffentlich.”	Sie haben direkt eine private IP eingegeben
“Der Hostname lässt sich zu keiner Adresse auflösen.”	prüfen Sie das DNS
“Der Hostname konnte nicht aufgelöst werden.”	das DNS ist fehlgeschlagen; versuchen Sie es erneut
“Der Host wird zu einer nicht öffentlichen Adresse aufgelöst.”	der Name zeigt in Ihr internes Netz

Bei der Auswahl der Ereignisse bedeutet “Eines der ausgewählten Ereignisse wird nicht erkannt.”, dass die gesendete Liste einen Namen enthält, den die Plattform nicht kennt — prüfen Sie ihn in der Tabelle der Ereignisse weiter unten. Und “Keine Webhook-URL konfiguriert – geben Sie eine an oder speichern Sie zuerst das Abonnement.” erscheint, wenn Sie Ereignisse abonnieren möchten, bevor es eine Adresse gibt.

Die Ereignisse

Ereignis	Auf dem Bildschirm	Wann es gesendet wird
document.completed	Dokument abgeschlossen	Alle haben unterschrieben, und das finale Dokument ist bereit
document.rejected	Dokument abgelehnt	Ein Unterzeichner hat abgelehnt
document.canceled	Dokument storniert	Das Dokument wurde storniert
document.expired	Dokument abgelaufen	Die Frist ist verstrichen, ohne dass es abgeschlossen wurde
document.pdf_application_failed	Fehler beim Anbringen der Signaturen im PDF	Die Signatur konnte nicht im PDF angebracht werden
recipient.signed	Unterzeichner hat unterschrieben	Ein Unterzeichner hat unterschrieben — einmal pro Unterzeichner
document.sent	Dokument zur Unterschrift gesendet	Das Dokument wurde veröffentlicht, und die Einladungen sind hinausgegangen

Die letzten beiden sind nicht endgültig: Das Dokument läuft danach weiter. Behandeln Sie kein Ereignis als „ist fertig“ — prüfen Sie den Status des Dokuments, der im Body mitkommt.

document.pdf_application_failed dürfen Sie nicht ignorieren: Es bedeutet, dass jemand unterschrieben hat, die Signatur aber nicht in die Datei gelangt ist. In AssinaJá erscheint das in den Dokumentdetails als Technisches Problem, mit Erneut versuchen — siehe Dokumente verfolgen und verwalten.

Der Header Idempotency-Key dient dazu, dass Ihre Seite Wiederholungen verwerfen kann, aber er hat nicht nur eine Form. Sie hängt davon ab, wohin das Ereignis geht und welches es ist:

Ziel	Ereignis	Schlüssel
Adresse des Dokuments (webhookUrl)	jedes außer recipient.signed	{documentPublicId}:{event}
Adresse des Dokuments	recipient.signed	{documentPublicId}:{event}:{recipientId}
Adresse der Organisation	jedes außer recipient.signed	{documentPublicId}:{event}:org
Adresse der Organisation	recipient.signed	{documentPublicId}:{event}:{recipientId}:org

Speichern und vergleichen Sie den gesamten Schlüssel, als undurchsichtigen Text. Zerlegen Sie ihn nicht. Haben Sie in Ihrer Datenbank eine Eindeutigkeitsbedingung auf (documento, evento) (Dokument, Ereignis), lehnt diese legitime Zustellungen ab: recipient.signed kommt einmal pro Unterzeichner, und ein Dokument mit eigener Adresse in einer Organisation, die ebenfalls eine Adresse konfiguriert hat, erzeugt zwei Zustellungen desselben Ereignisses mit unterschiedlichen Schlüsseln.

Das Webhook-Secret

Mit dem Secret können Sie sicher sein, dass die Anfrage wirklich von AssinaJá kommt. Es befindet sich unter Einstellungen → Entwickler, auf der Registerkarte Webhooks, in der Karte Webhook-Secret. Nur der Inhaber der Organisation sieht es.

Webhook-Secret:

Mit dem Secret wird die Signatur der an Ihren Webhook gesendeten Ereignisse geprüft.

Verwenden Sie beim ersten Mal Secret generieren und Kopieren, um es zu speichern. Danach zeigt die Karte das Secret verdeckt, mit Kopieren und Rotieren. Verlassen Sie die Seite nicht, ohne es gespeichert zu haben:

Speichern Sie diesen Wert jetzt – er wird nicht noch einmal angezeigt.

Das Secret wechseln

Rotieren erzeugt ein neues Secret, ohne die Zustellungen zu unterbrechen:

Möchten Sie das Secret wirklich rotieren? Das vorherige Secret bleibt 24 Stunden gültig.

Während dieser 24 Stunden — “Vorheriges Secret noch 24 Std. gültig.” — werden die Anfragen mit beiden Secrets signiert, durch Komma getrennt im selben Header. Deshalb muss die Prüfung eine Liste akzeptieren und nicht nur einen einzelnen Wert. Nach Ablauf dieser Frist wird nur noch das neue verwendet.

Die Signatur prüfen

Jede Anfrage enthält diese Header:

Header	Was er ist
X-AssinaJa-Signature	Die Signatur, v1=<hex>, oder mehrere durch Komma getrennt während einer Rotation
X-AssinaJa-Event	Der Name des Ereignisses
X-AssinaJa-Delivery	Eine neue Kennung bei jedem Versuch — nicht geeignet, um Wiederholungen zu verwerfen
X-AssinaJa-Timestamp	Die Uhrzeit, in Unix-Sekunden
Idempotency-Key	Siehe die Tabelle oben — vier mögliche Formen

Die Signatur ist ein HMAC-SHA256 über Uhrzeit und Body der Anfrage, verbunden durch einen Punkt — {timestamp}.{corpo} —, in hexadezimalen Kleinbuchstaben und mit dem Präfix v1=.

Der Schlüssel ist nicht das Secret, so wie Sie es kopiert haben. Das Secret ist base64url-codiert; der HMAC-Schlüssel sind die Bytes, die sich aus der Decodierung ergeben. Den Text direkt an die HMAC-Funktion zu übergeben, erzeugt eine Signatur, die nie übereinstimmt — das ist die häufigste Ursache für eine fehlschlagende Prüfung.

const crypto = require('crypto');

function verifyWebhookSignature(secret, timestamp, body, signatureHeader) {
  const message = `${timestamp}.${body}`;
  // o segredo é base64url — a chave são os bytes descodificados, não o texto
  const secretBytes = Buffer.from(secret, 'base64url');
  const expected = 'v1=' + crypto
    .createHmac('sha256', secretBytes)
    .update(message)
    .digest('hex');

  // durante uma rotação vêm as duas assinaturas
  const signatures = signatureHeader.split(',').map(s => s.trim());
  return signatures.some(sig => sig === expected);
}

Verwenden Sie den Body so, wie er angekommen ist, roh. Wenn Sie ihn durch einen JSON-Parser schicken und erneut serialisieren, ändern sich die Bytes, und die Signatur stimmt nicht mehr.

Drei Dinge, die Sie immer tun sollten

1. Die Signatur prüfen, bevor Sie dem Inhalt vertrauen.
2. Anfragen ablehnen, die älter als 5 Minuten sind, anhand von X-AssinaJa-Timestamp — das verhindert, dass jemand eine abgefangene alte Anfrage erneut sendet.
3. Wiederholungen verwerfen anhand von Idempotency-Key, denn eine erneute Zustellung ist normal.

Was die Plattform mit Ihrer Antwort macht

Was Sie antworten	Was passiert
2xx	Zugestellt. Es gibt keinen neuen Versuch. Der Body der Antwort darf höchstens 4 KB groß sein.
3xx	Neuer Versuch — Weiterleitungen werden nicht verfolgt.
4xx	Neuer Versuch, genau wie bei 5xx.
5xx	Neuer Versuch.
Keine Antwort innerhalb von 10 Sekunden	Neuer Versuch.

Nur eine 2xx-Antwort zählt als zugestellt. Es gibt keinen Code, mit dem die Plattform absichtlich aufgibt: Wenn eine Zustellung aufhören soll, antworten Sie mit 2xx und verwerfen den Inhalt auf Ihrer Seite.

Die Versuche erfolgen im Abstand von 1 min, 2 min, 5 min, 15 min, 30 min, 60 min und 60 min. Es sind insgesamt acht, und der achte ist eine echte Zustellung — erst wenn er fehlschlägt, wird die Zustellung als fehlgeschlagen markiert.

Eine ausgefallene Adresse stellt die Unterschrift nicht infrage

Wenn die acht Versuche erschöpft sind, wird das Dokument mit Technisches Problem markiert. Die Ursache wird gespeichert, und die Meldung nennt sie:

Die Signatur wurde angebracht. Fehlgeschlagen ist die Benachrichtigung an die Webhook-Adresse Ihrer Organisation – prüfen Sie Ihren Server und senden Sie die Zustellung unter Einstellungen → Entwickler erneut.

Ein älteres Dokument hat möglicherweise keine gespeicherte Ursache; dann zeigt es die allgemeine Meldung “Bei der Verarbeitung dieses Dokuments ist ein technisches Problem aufgetreten.”

Prüfen, ob es angekommen ist

Die Details jedes Dokuments zeigen die letzte Zustellung dieses Dokuments, unabhängig vom Ereignis, in der Karte Integration — mit Webhook (dem Namen des Ereignisses), Status, Versuche, Zugestellt am und, bei einem Fehlschlag, Fehler. Das ist der schnellste Ort, um „AssinaJá hat nicht gesendet“ von „mein Server hat nicht angenommen“ zu unterscheiden. In dieser Karte gibt es keine Schaltfläche zum erneuten Senden.

Um den vollständigen Verlauf der Organisation zu sehen und fehlgeschlagene Zustellungen erneut zu senden, gehen Sie zu Einstellungen → Entwickler → Webhooks, in den Abschnitt Zustellungen unter der Adresse und dem Secret:

Jedes gesendete Ereignis mit der Antwort Ihres Endpunkts. Fehlgeschlagene Zustellungen können erneut gesendet werden.

Jede Zeile hat Ereignis, Adresse, Status (Zugestellt oder Fehlgeschlagen), Versuche, Datum und Letzter Fehler; die fehlgeschlagenen haben Erneut senden, das mit “Zustellung erneut gesendet. Der Endpunkt hat mit {Code} geantwortet.” antwortet. Nur der Inhaber der Organisation hat Zugriff auf diesen Bildschirm.

Greift das erneute Senden nicht, sagt der Bildschirm, warum:

Diese Zustellung existiert nicht mehr.

Diese Zustellung wurde bereits empfangen – nur fehlgeschlagene werden erneut gesendet.

Diese Zustellung kann derzeit nicht erneut gesendet werden.

Siehe auch

• Einen API-Schlüssel erstellen
• Dokumente verfolgen und verwalten
• Lebenszyklus eines Dokuments