Ereignisse von Drime Sign per Webhook empfangen

Mit einem Webhook ruft Drime Ihren Server jedes Mal auf, wenn mit Ihren Signaturanfragen etwas passiert. Jeder Aufruf ist ein JSON-POST, signiert mit einem Secret, damit Ihr Server prüfen kann, dass er von Drime stammt.

#Einen Webhook hinzufügen

1. Öffnen Sie Einstellungen > Entwickler > Webhooks.

   In Sign können Sie auch auf Einstellungen klicken, den Tab Webhooks öffnen und dann Entwicklereinstellungen öffnen wählen.

2. Klicken Sie auf Webhook hinzufügen.

3. Geben Sie unter Endpunkt-URL die Adresse Ihres Servers ein, der die Aufrufe empfängt.

4. Stellen Sie unter Ereignisse jedes gewünschte Ereignis auf Ein und klicken Sie auf Webhook erstellen.

   Webhook erstellt bestätigt es.

5. Kopieren Sie jetzt das Secret und klicken Sie dann auf Fertig.

   Webhook-Secret, jetzt kopieren: Es wird nur einmal angezeigt. Bewahren Sie es an einem sicheren Ort auf.

#Die Ereignisse

#Was Drime sendet

Jeder Aufruf enthält diese Header:

• X-Drime-Event: das Ereignis, zum Beispiel envelope.completed;

• X-Drime-Delivery: die Nummer der Zustellung;

• X-Drime-Signature: sha256=, gefolgt vom HMAC SHA-256 des Rohinhalts, berechnet mit Ihrem Secret.

Der JSON-Inhalt enthält event_type, event_uuid, timestamp und data, das betroffene Dokument mit seinen Unterzeichnern. Der Bereich Webhooks zeigt unter Beispielanfrage & Signaturprüfung ein vollständiges Beispiel.

Eine Zustellung kann mehrfach ankommen: Verwenden Sie event_uuid, um jedes Ereignis nur einmal zu verarbeiten.

#Die Signatur prüfen

Berechnen Sie mit Ihrem Secret den HMAC SHA-256 des rohen Anfrageinhalts und vergleichen Sie ihn mit dem Header X-Drime-Signature. Zum Beispiel in Node.js:

import crypto from 'node:crypto';

function isFromDrime(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return header.length === expected.length && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Verwenden Sie den Inhalt genau so, wie er empfangen wurde, vor jedem JSON-Parsing.

#Testen und Zustellungen verfolgen

• Test senden sendet ein Testereignis: Testereignis in der Warteschlange, prüfen Sie das Zustellungsprotokoll.

• Zustellungen listet jeden Aufruf mit seinem Status auf: Erfolg, Ausstehend oder Fehlgeschlagen. Erneut senden sendet eine Zustellung noch einmal.

• Wenn Ihr Server nicht oder mit einem Fehler antwortet, versucht Drime es erneut, bis zu 10 Versuche über etwa 34 Stunden.

• Der Schalter Ein / Aus pausiert einen Webhook, ohne ihn zu löschen: Webhook pausiert bestätigt es, und Webhook aktiviert, wenn Sie ihn wieder einschalten.

#Das Secret ändern oder den Webhook löschen

• Schlüssel neu generieren erstellt ein neues Secret. Die App warnt: Secret neu generieren? Ihr aktuelles Secret funktioniert sofort nicht mehr. Aktualisieren Sie Ihren Server sofort.

• Löschen entfernt den Webhook: Diesen Webhook und seinen Zustellungsverlauf löschen?

#Wenn es nicht funktioniert

#Nächste Schritte

• Eine App entwickeln oder Webhooks einrichten

• Ein API-Token erstellen

• Was das Prüfzertifikat eines unterschriebenen Dokuments enthält