Webhook''s
Ontvang realtime ondertekeningsgebeurtenissen via HTTP met door HMAC ondertekende leveringen, automatische nieuwe pogingen en een vangnet voor opnieuw afspelen vanaf de console.
SHA-256 verzoek om ondertekening
Per-webhook geheim, verzonden als X-Endorsed-Signature
Time-out voor bezorging
Retourneer 2xx binnen het venster, anders mislukt de poging
Opnieuw geprobeerd na de eerste poging
60s, 5m, 15m, 1u, dan 6u
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.
| Gebeurtenistype | Als het vuurt | Sleutel `gegevens`velden |
|---|---|---|
| document.created | Je uploadt een document via de API | documentId, klantId, externDocumentId |
| document.sent | Ondertekenlink verzonden naar eerste ontvanger | documentId, klantId, kanaal |
| document.viewed | Ondertekenaar opent de ondertekenlink | documentId, e-mail ondertekenaar, bekekenOp |
| document.signed | Individuele ondertekenaar voltooit zijn stap | documentId, ondertekenaarE-mail, ondertekendAt |
| document.completed | Alle partijen hebben getekend | documentId, voltooidAt, downloadUrl |
| document.declined | Een ondertekenaar weigert expliciet | documentId, e-mailadres ondertekenaar, reden |
| document.expired | Het document bereikt de vervaldatum zonder ondertekening | documentId, verlopenAt |
| signing.started | Ondertekensessietoken is ingewisseld | documentId, sessie-ID, e-mail van de ondertekenaar |
| signing.completed | Ondertekeningssessie is voltooid (ondertekend of geweigerd) | documentId, sessie-Id, resultaat |
| klant.aangemaakt / .bijgewerkt / .verwijderd | U muteert een klantrecord | klantId, externeKlantId |
| sjabloon.gemaakt / .bijgewerkt | Je muteert een sjabloon | templateId, 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.
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
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
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
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
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.

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.