Entwickler

Webhooks

Empfangen Sie Signaturereignisse in Echtzeit über HTTP mit HMAC-signierten Zustellungen, automatischen Wiederholungsversuchen und einem Sicherheitsnetz für die Wiedergabe von der Konsole.

HMAC

SHA-256-Anforderungssignatur

Per-webhook Geheimnis, gesendet als X-Endorsed-Signature

10s

Lieferzeitüberschreitung

Geben Sie 2xx innerhalb des Fensters zurück, sonst schlägt der Versuch fehl

5×

Wiederholungsversuche nach dem ersten Versuch

60s, 5m, 15m, 1h, dann 6h

Replay

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.

EreignistypWenn es feuertSchlüsseldatenfelder
document.createdSie laden ein Dokument über den API hochdocumentId, customerId, externalDocumentId
document.sentSignaturlink an ersten Empfänger gesendetdocumentId, customerId, Kanal
document.viewedSigner öffnet den SignaturlinkDokument-ID, Unterzeichner-E-Mail, angezeigt am
document.signedEinzelner Unterzeichner schließt seinen Schritt abdocumentId, signerEmail, signiertAt
document.completedAlle Parteien haben unterschriebenDokument-ID, abgeschlossen um, Download-URL
document.declinedEin Unterzeichner lehnt ausdrücklich abDokument-ID, Unterzeichner-E-Mail, Grund
document.expiredDokument erreicht sein Ablaufdatum ohne UnterschriftdocumentId, abgelaufen um
signing.startedSignatursitzungstoken wird eingelöstdocumentId, sessionId, signerEmail
signing.completedSignatursitzung beendet (signiert oder abgelehnt)Dokument-ID, Sitzungs-ID, Ergebnis
Kunde.erstellt / .aktualisiert / .gelöschtSie ändern einen KundendatensatzKunden-ID, externe Kunden-ID
Vorlage.erstellt / .aktualisiertSie mutieren eine VorlagetemplateId, 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.

typescript
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. 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. 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. 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. 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.

Lieferereignisverlauf mit Dokumentlebenszykluseinträgen
Lieferereignisverlauf – signierte Lebenszyklusereignisse mit Zeitstempeln und Statusergebnissen zur Betriebsvalidierung.

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.