Sviluppatori

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.

HMAC

SHA-256 firma della richiesta

Per-webhook segreto, inviato come X-Endorsed-Signature

10s

Timeout di consegna

Restituisci 2xx nella finestra altrimenti il tentativo fallirà

5×

Riprova dopo il primo tentativo

Anni ''60, 5 minuti, 15 minuti, 1 ora, poi 6 ore

Replay

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 eventoQuando si attivaCampi chiave "dati".
document.createdCarichi un documento tramite APIIDdocumento, ID cliente, ID documento esterno
document.sentLink di firma inviato al primo destinatarioIDdocumento, ID cliente, canale
document.viewedSigner apre il collegamento per la firmaIDdocumento, emailfirmatario, visualizzatoAt
document.signedIl singolo firmatario completa il passaggiodocumentId, signerEmail, SignedAt
document.completedTutte le parti hanno firmatodocumentId, completatoAt, downloadUrl
document.declinedUn firmatario rifiuta esplicitamenteIDdocumento, emailfirmatario, motivo
document.expiredIl documento raggiunge la data di scadenza senza firmaIDdocumento, scadutoAt
signing.startedIl token della sessione di firma è stato riscattatodocumentId, sessionId, firmatarioEmail
signing.completedLa sessione di firma termina (firmato o rifiutato)documentId, sessionId, risultato
cliente.creato / .aggiornato / .eliminatoHai modificato il record di un clienteID cliente, ID cliente esterno
template.creato / .aggiornatoHai modificato un modellotemplateId, 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.

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

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

Cronologia eventi di consegna con voci del ciclo di vita del documento
Cronologia eventi di consegna: eventi del ciclo di vita firmati con timestamp e risultati dello stato per la convalida operativa.

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.