Ontwikkelaars

Webhook''s

Ontvang realtime ondertekeningsgebeurtenissen via HTTP met door HMAC ondertekende leveringen, automatische nieuwe pogingen en een vangnet voor opnieuw afspelen vanaf de console.

HMAC

SHA-256 verzoek om ondertekening

Per-webhook geheim, verzonden als X-Endorsed-Signature

10s

Time-out voor bezorging

Retourneer 2xx binnen het venster, anders mislukt de poging

5×

Opnieuw geprobeerd na de eerste poging

60s, 5m, 15m, 1u, dan 6u

Replay

Vanaf de ontwikkelaarsconsole

Inspecteer elke poging en speel individuele gebeurtenissen opnieuw

Wat u kunt doen met webhook-evenementen

Elke belangrijke levenscyclustransitie zendt een getypte gebeurtenis uit. Gebruik ze om uw eigen gegevens bij te werken zonder te peilen.

✅

Activeer stroomafwaartse acties

Wanneer een envelop volledig is ondertekend, update dan uw CRM, geef een ingerichte bron vrij of stuur een bevestiging in uw eigen product - allemaal zonder de API te pollen.

🔄

Synchroniseer documentstatus

Houd uw database gesynchroniseerd met de levenscyclus van de ondertekening: verzonden, geopend, ondertekend, geweigerd, verlopen, ongeldig gemaakt. Eén gebeurtenis per transitie, geen polling-lus vereist.

📋

Audit- en nalevingsregistratie

Voed webhook gebeurtenissen toe aan uw eigen auditopslag. Correlatie-ID''s koppelen elke gebeurtenis terug aan het oorspronkelijke API-verzoek voor volledige traceerbaarheid.

🔁

Mislukte leveringen opnieuw afspelen

Gebeurtenissen die de ladder voor nieuwe pogingen uitputten, belanden in een wachtrij met dode letters die je kunt inspecteren in de ontwikkelaarsconsole en opzettelijk opnieuw kunt afspelen.

Webhook gebeurtenisreferentie

Registreer een webhook, kies welke gebeurtenissen u wilt, en EndorsedSign levert een JSON-payload met `event`, `tenantId`, `timestamp` en `data`. Gebeurtenisnamen komen overeen met de tekenreeksen die u verzendt in de webhook create-oproep.

GebeurtenistypeAls het vuurtSleutel `gegevens`velden
document.createdJe uploadt een document via de APIdocumentId, klantId, externDocumentId
document.sentOndertekenlink verzonden naar eerste ontvangerdocumentId, klantId, kanaal
document.viewedOndertekenaar opent de ondertekenlinkdocumentId, e-mail ondertekenaar, bekekenOp
document.signedIndividuele ondertekenaar voltooit zijn stapdocumentId, ondertekenaarE-mail, ondertekendAt
document.completedAlle partijen hebben getekenddocumentId, voltooidAt, downloadUrl
document.declinedEen ondertekenaar weigert explicietdocumentId, e-mailadres ondertekenaar, reden
document.expiredHet document bereikt de vervaldatum zonder ondertekeningdocumentId, verlopenAt
signing.startedOndertekensessietoken is ingewisselddocumentId, sessie-ID, e-mail van de ondertekenaar
signing.completedOndertekeningssessie is voltooid (ondertekend of geweigerd)documentId, sessie-Id, resultaat
klant.aangemaakt / .bijgewerkt / .verwijderdU muteert een klantrecordklantId, externeKlantId
sjabloon.gemaakt / .bijgewerktJe muteert een sjabloontemplateId, naam

Volledige lijst bevindt zich in backend `WEBHOOK_EVENTS`. Voeg abonnementen toe of beperk ze per webhook: de leveringspijplijn verspreidt één HTTP-aanroep per geregistreerd eindpunt.

Verifiëren van webhook-handtekeningen (Node.js)

Elke levering bevat een `X-Endorsed-Signature` header: `t={unix_seconds},v1={hex}`. `v1` is HMAC-SHA256 van `{timestamp}.{rawBody}` met behulp van het geheim dat werd geretourneerd toen webhook werd gemaakt. Tijdstempels buiten ±5 minuten weigeren. `X-Webhook-Signature` kan nog steeds verschijnen op testleveringen van de ontwikkelaarsportal als een verouderde alias die alleen in de hoofdtekst is. Controleer `X-Endorsed-Signature`. Vereisten: je webhook-geheim in een env var, een Express-route die het rauwe lichaam behoudt. Verwachte output: niet-herkende of gemanipuleerde payloads worden afgewezen met 401 voordat een handler wordt uitgevoerd.

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);
  },
);

Retourneer 2xx binnen 30s, anders wordt de levering gemarkeerd als mislukt. Mislukte pogingen probeer het opnieuw met de ladder erboven en blijf herspeelbaar vanaf de ontwikkelaarsconsole.

Hoe u een webhook eindpunt instelt

  1. 1

    Maak het eindpunt in uw app

    Voeg een route toe die POST-verzoeken accepteert en binnen 10 seconden HTTP 200 retourneert. Elke 2xx-reactie geldt als een succesvolle levering.

  2. 2

    Registreer het eindpunt in uw tenantinstellingen

    Ga naar Beheer → Instellingen → Webhook''s. Voer uw eindpunt-URL in en selecteer de gewenste gebeurtenistypen. Per eindpunt wordt een ondertekeningsgeheim gegenereerd.

  3. 3

    Verifieer de handtekening bij elk verzoek

    Lees `X-Endorsed-Signature`. Bereken HMAC-SHA256 opnieuw via `{timestamp}.{rawBody}` en constante tijd vergelijken met `v1` (zie het codevoorbeeld hierboven). Weiger een ontbrekende header, een slechte hexadecimale waarde, een tijdstempel buiten ±5 minuten of een HMAC-mismatch. `X-Webhook-Signature` is een verouderde alias bij sommige testleveringen. Beschouw dit niet als het live contract.

  4. 4

    Retourneer 2xx snel, proces asynchroon

    Bevestig de levering met 200 binnen 10 seconden en zet de gebeurtenistekst in de wachtrij voor asynchrone verwerking. De ontwikkelaarsconsole toont elke poging (headers, hoofdtekst, status, timing) en laat u elke levering opnieuw afspelen. U hoeft de bronondertekeningsstroom niet opnieuw te activeren alleen maar om uw handler te testen.

Veelgestelde vragen

Een echte webhook payload — document voltooid

Wanneer alle partijen hebben ondertekend, POST EndorsedSign deze payload naar uw geregistreerde eindpunt. Controleer de HMAC-handtekening, plaats deze in de wachtrij en bevestig met 200.

Gebeurtenisgeschiedenis van levering met gegevens over de levenscyclus van documenten
Gebeurtenisgeschiedenis van levering — ondertekende levenscyclusgebeurtenissen met tijdstempels en statusresultaten voor operationele validatie.

Sluit uw eerste webhook aan

Claim een sandbox, registreer het eindpunt in Beheerder → Ontwikkelaar → Webhook''s en inspecteer of speel elke levering opnieuw af vanaf de ontwikkelaarsconsole.