Webhooks
Empfangen Sie Signaturereignisse in Echtzeit über HTTP mit HMAC-signierten Zustellungen, automatischen Wiederholungsversuchen und einem Sicherheitsnetz für die Wiedergabe von der Konsole.
SHA-256-Anforderungssignatur
Per-webhook Geheimnis, gesendet als X-Endorsed-Signature
Lieferzeitüberschreitung
Geben Sie 2xx innerhalb des Fensters zurück, sonst schlägt der Versuch fehl
Wiederholungsversuche nach dem ersten Versuch
60s, 5m, 15m, 1h, dann 6h
Von der Entwicklerkonsole
Inspizieren Sie jeden Versuch und wiederholen Sie einzelne Ereignisse
Was Sie mit webhook-Ereignissen machen können
Jeder bedeutende Lebenszyklusübergang gibt ein typisiertes Ereignis aus. Verwenden Sie sie, um Ihre eigenen Datensätze ohne Abfrage zu aktualisieren.
Nachgelagerte Aktionen auslösen
Wenn ein Umschlag vollständig signiert ist, aktualisieren Sie Ihr CRM, geben Sie eine bereitgestellte Ressource frei oder senden Sie eine Bestätigung in Ihrem eigenen Produkt – alles ohne Abfrage des API.
Dokumentstatus synchronisieren
Halten Sie Ihre Datenbank mit dem Signaturlebenszyklus synchron: gesendet, geöffnet, signiert, abgelehnt, abgelaufen, ungültig. Ein Ereignis pro Übergang, keine Abfrageschleife erforderlich.
Audit- und Compliance-Protokollierung
Füttern Sie webhook-Ereignisse in Ihren eigenen Prüfspeicher. Korrelations-IDs verknüpfen jedes Ereignis zur vollständigen Rückverfolgbarkeit mit der ursprünglichen „P1“-Anfrage.
Wiederholen Sie fehlgeschlagene Lieferungen
Ereignisse, die die Wiederholungsleiter erschöpfen, landen in einer Warteschlange für unzustellbare Nachrichten, die Sie in der Entwicklerkonsole überprüfen und absichtlich wiederholen können.
Webhook Ereignisreferenz
Registrieren Sie ein webhook, wählen Sie die gewünschten Ereignisse aus und EndorsedSign liefert eine JSON-Nutzlast mit „Ereignis“, „Mandanten-ID“, „Zeitstempel“ und „Daten“. Ereignisnamen stimmen mit den Zeichenfolgen überein, die Sie im webhook-Erstellungsaufruf senden.
| Ereignistyp | Wenn es feuert | Schlüsseldatenfelder |
|---|---|---|
| document.created | Sie laden ein Dokument über den API hoch | documentId, customerId, externalDocumentId |
| document.sent | Signaturlink an ersten Empfänger gesendet | documentId, customerId, Kanal |
| document.viewed | Signer öffnet den Signaturlink | Dokument-ID, Unterzeichner-E-Mail, angezeigt am |
| document.signed | Einzelner Unterzeichner schließt seinen Schritt ab | documentId, signerEmail, signiertAt |
| document.completed | Alle Parteien haben unterschrieben | Dokument-ID, abgeschlossen um, Download-URL |
| document.declined | Ein Unterzeichner lehnt ausdrücklich ab | Dokument-ID, Unterzeichner-E-Mail, Grund |
| document.expired | Dokument erreicht sein Ablaufdatum ohne Unterschrift | documentId, abgelaufen um |
| signing.started | Signatursitzungstoken wird eingelöst | documentId, sessionId, signerEmail |
| signing.completed | Signatursitzung beendet (signiert oder abgelehnt) | Dokument-ID, Sitzungs-ID, Ergebnis |
| Kunde.erstellt / .aktualisiert / .gelöscht | Sie ändern einen Kundendatensatz | Kunden-ID, externe Kunden-ID |
| Vorlage.erstellt / .aktualisiert | Sie mutieren eine Vorlage | templateId, Name |
Die vollständige Liste befindet sich im Backend „WEBHOOK_EVENTS“. Fügen Sie Abonnements pro webhook hinzu oder grenzen Sie sie ein – die Lieferpipeline verteilt einen HTTP-Aufruf pro registriertem Endpunkt.
Verifizierung von webhook-Signaturen (Node.js)
Jede Lieferung enthält einen „X-Endorsed-Signature“-Header: „t=“.{unix_seconds},v1={hex}`. „v1“ ist HMAC-SHA256 von „{timestamp}.{rawBody}` unter Verwendung des Geheimnisses, das bei der Erstellung von webhook zurückgegeben wurde. Zeitstempel außerhalb von ±5 Minuten ablehnen. „X-Webhook-Signature“ erscheint möglicherweise immer noch in Testlieferungen des Entwicklerportals als veralteter Nur-Text-Alias – überprüfen Sie „X-Endorsed-Signature“. Voraussetzungen: Ihr webhook-Geheimnis in einer Umgebungsvariable, eine Express-Route, die den Rohkörper behält. Erwartete Ausgabe: Nicht erkannte oder manipulierte Nutzdaten werden mit 401 abgelehnt, bevor ein Handler ausgeführt wird.
import crypto from 'node:crypto';
import express from 'express';
const WEBHOOK_SECRET = process.env.ENDORSED_WEBHOOK_SECRET!;
const TOLERANCE_SECONDS = 5 * 60;
export function verifyWebhookSignature(
rawBody: string,
header: string | undefined,
nowSeconds = Math.floor(Date.now() / 1000),
): boolean {
if (!header) return false;
let timestamp: number | null = null;
let v1 = '';
for (const part of header.split(',')) {
const eq = part.indexOf('=');
if (eq === -1) continue;
const key = part.slice(0, eq).trim();
const value = part.slice(eq + 1).trim();
if (key === 't' && /^\d+$/.test(value)) timestamp = Number.parseInt(value, 10);
if (key === 'v1' && /^[a-f0-9]{64}$/i.test(value)) v1 = value.toLowerCase();
}
if (timestamp === null || !v1) return false;
if (Math.abs(nowSeconds - timestamp) > TOLERANCE_SECONDS) return false;
const expected = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(timestamp + '.' + rawBody)
.digest('hex');
const a = Buffer.from(expected, 'hex');
const b = Buffer.from(v1, 'hex');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post(
'/webhooks/endorsed',
express.json({ verify: (req, _res, buf) => { (req as any).rawBody = buf.toString('utf8'); } }),
(req, res) => {
const sig = req.header('X-Endorsed-Signature');
if (!verifyWebhookSignature((req as any).rawBody, sig)) {
return res.status(401).send('Invalid signature');
}
res.sendStatus(200);
},
);Return 2xx innerhalb von 30 Sekunden oder die Lieferung wird als fehlgeschlagen markiert. Fehlgeschlagene Versuche werden mit der oben genannten Leiter wiederholt und können weiterhin über die Entwicklerkonsole wiedergegeben werden.
So richten Sie einen webhook-Endpunkt ein
- 1
Erstellen Sie den Endpunkt in Ihrer App
Fügen Sie eine Route hinzu, die POST-Anfragen akzeptiert und innerhalb von 10 Sekunden HTTP 200 zurückgibt. Jede 2xx-Antwort gilt als erfolgreiche Zustellung.
- 2
Registrieren Sie den Endpunkt in Ihren Mandanteneinstellungen
Gehen Sie zu Admin → Einstellungen → Webhooks. Geben Sie Ihre Endpunkt-URL ein und wählen Sie die gewünschten Ereignistypen aus. Pro Endpunkt wird ein Signaturgeheimnis generiert.
- 3
Überprüfen Sie die Signatur bei jeder Anfrage
Lesen Sie „X-Endorsed-Signature“. Berechnen Sie HMAC-SHA256 über ` neu{timestamp}.{rawBody}` und konstanter Zeitvergleich mit `v1` (siehe Codebeispiel oben). Lehnen Sie einen fehlenden Header, einen falschen Hexadezimalwert, einen Zeitstempel außerhalb von ±5 Minuten oder eine HMAC-Nichtübereinstimmung ab. „X-Webhook-Signature“ ist bei einigen Testlieferungen ein veralteter Alias – behandeln Sie ihn nicht als Live-Vertrag.
- 4
2xx schnell zurückgeben, asynchron verarbeiten
Bestätigen Sie die Zustellung innerhalb von 10 Sekunden mit 200 und stellen Sie den Ereignistext für die asynchrone Verarbeitung in die Warteschlange. Die Entwicklerkonsole zeigt jeden Versuch (Header, Text, Status, Zeitpunkt) und ermöglicht Ihnen die Wiedergabe jeder Zustellung – Sie müssen den Quellsignaturfluss nicht erneut auslösen, nur um Ihren Handler zu testen.
Häufige Fragen
Eine echte webhook-Nutzlast – Dokument abgeschlossen
Wenn alle Parteien signiert haben, sendet EndorsedSign diese Nutzlast an Ihren registrierten Endpunkt. Überprüfen Sie die HMAC-Signatur, stellen Sie sie in die Warteschlange und bestätigen Sie mit 200.

Verkabeln Sie Ihr erstes webhook
Beanspruchen Sie eine Sandbox, registrieren Sie den Endpunkt unter Admin → Entwickler → Webhooks und überprüfen oder spielen Sie jede Lieferung über die Entwicklerkonsole ab.