Webhooks
Ricevi eventi di firma in tempo reale su HTTP con consegne firmate HMAC, tentativi automatici e una rete di sicurezza di riproduzione dalla console.
SHA-256 firma della richiesta
Per-webhook segreto, inviato come X-Endorsed-Signature
Timeout di consegna
Restituisci 2xx nella finestra altrimenti il tentativo fallirà
Riprova dopo il primo tentativo
Anni ''60, 5 minuti, 15 minuti, 1 ora, poi 6 ore
Dalla console dello sviluppatore
Ispeziona ogni tentativo e riproduci i singoli eventi
Cosa puoi fare con gli eventi webhook
Ogni transizione significativa del ciclo di vita emette un evento tipizzato. Usali per aggiornare i tuoi record senza polling.
Attiva azioni downstream
Quando una busta è completamente firmata, aggiorna il tuo CRM, rilascia una risorsa fornita o invia una conferma all''interno del tuo prodotto, il tutto senza interrogare API.
Sincronizza lo stato del documento
Mantieni il tuo database sincronizzato con il ciclo di vita della firma: inviato, aperto, firmato, rifiutato, scaduto, annullato. Un evento per transizione, non è richiesto alcun ciclo di polling.
Registrazione di audit e conformità
Inserisci gli eventi webhook nel tuo archivio di controllo. Gli ID di correlazione collegano ogni evento alla richiesta API originaria per la tracciabilità completa.
Replay consegne fallite
Gli eventi che esauriscono la scala dei tentativi finiscono in una coda di lettere non recapitate che puoi controllare nella console degli sviluppatori e riprodurre intenzionalmente.
Webhook riferimento evento
Registra un webhook, scegli gli eventi che desideri e EndorsedSign fornisce un payload JSON con `event`, `tenantId`, `timestamp` e `data`. I nomi degli eventi corrispondono alle stringhe inviate nella chiamata di creazione webhook.
| Tipo evento | Quando si attiva | Campi chiave "dati". |
|---|---|---|
| document.created | Carichi un documento tramite API | IDdocumento, ID cliente, ID documento esterno |
| document.sent | Link di firma inviato al primo destinatario | IDdocumento, ID cliente, canale |
| document.viewed | Signer apre il collegamento per la firma | IDdocumento, emailfirmatario, visualizzatoAt |
| document.signed | Il singolo firmatario completa il passaggio | documentId, signerEmail, SignedAt |
| document.completed | Tutte le parti hanno firmato | documentId, completatoAt, downloadUrl |
| document.declined | Un firmatario rifiuta esplicitamente | IDdocumento, emailfirmatario, motivo |
| document.expired | Il documento raggiunge la data di scadenza senza firma | IDdocumento, scadutoAt |
| signing.started | Il token della sessione di firma è stato riscattato | documentId, sessionId, firmatarioEmail |
| signing.completed | La sessione di firma termina (firmato o rifiutato) | documentId, sessionId, risultato |
| cliente.creato / .aggiornato / .eliminato | Hai modificato il record di un cliente | ID cliente, ID cliente esterno |
| template.creato / .aggiornato | Hai modificato un modello | templateId, nome |
L''elenco completo si trova nel backend `WEBHOOK_EVENTS`. Aggiungi o restringi gli abbonamenti per webhook: la pipeline di distribuzione distribuisce una chiamata HTTP per endpoint registrato.
Verifica delle firme webhook (Node.js)
Ogni consegna include un''intestazione `X-Endorsed-Signature`: `t={unix_seconds},v1={hex}`. "v1" è HMAC-SHA256 di "{timestamp}.{rawBody}` utilizzando il segreto restituito quando è stato creato webhook. Rifiuta timestamp al di fuori di ±5 minuti. `X-Webhook-Signature` potrebbe ancora apparire nelle consegne di test del portale degli sviluppatori come alias deprecato solo per il corpo: verifica `X-Endorsed-Signature`. Prerequisiti: il tuo segreto webhook in un env var, un percorso Express che mantiene il corpo grezzo. Output previsto: i payload non riconosciuti o manomessi vengono rifiutati con 401 prima dell''esecuzione di qualsiasi gestore.
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);
},
);Restituisci 2xx entro 30 secondi altrimenti la consegna verrà contrassegnata come non riuscita. I tentativi falliti riprovano con la scala sopra e rimangono riproducibili dalla console per sviluppatori.
Come impostare un endpoint webhook
- 1
Crea l''endpoint nella tua app
Aggiungi un percorso che accetta richieste POST e restituisce HTTP 200 entro 10 secondi. Qualsiasi risposta 2xx conta come consegna riuscita.
- 2
Registra l''endpoint nelle impostazioni del tenant
Vai ad Amministrazione → Impostazioni → Webhooks. Inserisci l''URL dell''endpoint e seleziona i tipi di eventi desiderati. Viene generato un segreto di firma per endpoint.
- 3
Verifica la firma su ogni richiesta
Leggi `X-Endorsed-Signature`. Ricalcola HMAC-SHA256 su `{timestamp}.{rawBody}` e il tempo costante si confrontano con `v1` (vedi l''esempio di codice sopra). Rifiuta un''intestazione mancante, un valore esadecimale errato, un timestamp superiore a ±5 minuti o una mancata corrispondenza HMAC. "X-Webhook-Signature" è un alias deprecato su alcune consegne di prova: non trattarlo come un contratto attivo.
- 4
Restituisci 2xx rapidamente, elabora in modo asincrono
Conferma la consegna con 200 entro 10 secondi e accoda il corpo dell''evento per l''elaborazione asincrona. La console per sviluppatori mostra ogni tentativo (intestazioni, corpo, stato, tempistica) e ti consente di riprodurre qualsiasi consegna, senza bisogno di riattivare il flusso di firma dell''origine solo per testare il tuo gestore.
Domande comuni
Un carico utile webhook reale: documento completato
Quando tutte le parti hanno firmato, EndorsedSign POSTA questo payload sul tuo endpoint registrato. Verificare la firma HMAC, accodare e riconoscere con 200.

Collega il tuo primo webhook
Richiedi un sandbox, registra l''endpoint in Amministrazione → Sviluppatore → Webhooks e controlla o riproduci ogni consegna dalla console dello sviluppatore.