Invia gli eventi dei documenti al tuo sistema con i webhook
Un webhook invia al tuo URL un messaggio JSON firmato se un documento è inviato, aperto, firmato, completato, rifiutato, scaduto o annullato. Richiede Pro; lo impostano proprietari e amministratori.
In questa pagina
Un webhook invia un messaggio a un tuo URL ogni volta che succede qualcosa a un documento, così il tuo sistema può reagire. I webhook fanno parte di Pro: funzionano in uno spazio di lavoro finché uno dei suoi proprietari ha Pro, e solo proprietari e amministratori possono gestirli. Ogni spazio di lavoro ha i propri.
Aggiungi un webhook
- Apri Impostazioni e branding nel menu dell'account e vai in Integrazioni.
- Premi Aggiungi webhook.
- Inserisci l'URL dell'endpoint. Deve iniziare con
https://ed essere pubblico: gli indirizzi di reti private, gli indirizzi di Sealsimple e gli URL con nome utente e password vengono rifiutati. - Se vuoi, aggiungi un Nome, scegli gli Eventi (all'inizio sono tutti spuntati) e premi Aggiungi webhook.
- Copia la Chiave di firma che compare e premi Invia evento di prova.
Uno spazio di lavoro può avere fino a 10 webhook.
Eventi
document.sent: Documento inviatodocument.viewed: Aperto da un destinatario, una volta per destinatariodocument.signed: Firmato da un firmatario, una volta per firmatariodocument.completed: Completato: hanno firmato tuttidocument.declined: Rifiutatodocument.expired: Scadutodocument.canceled: Annullato
Cosa inviamo
Una richiesta POST con un corpo JSON: id (uguale a ogni tentativo, così puoi saltare i duplicati), event, created_at, workspace_id, un document con id, title, status e url, e per gli eventi che riguardano una persona un recipient con name, email e role. Un documento annullato ha lo stato voided. Il PDF firmato non viene inviato: recuperalo con l'API REST quando il documento è completato. L'evento di prova ha l'evento test e un documento e un firmatario fittizi.
Verifica la firma
Ogni richiesta ha un'intestazione Sealsimple-Signature come t=1700000000,v1=…, insieme a Sealsimple-Event e Sealsimple-Delivery. Per verificarla:
- Prendi il corpo grezzo della richiesta, esattamente come è arrivato.
- Leggi
t(un orario Unix in secondi) ev1dall'intestazione. - Calcola l'HMAC-SHA256 di
t, di un punto e del corpo, usando come chiave l'intera chiave di firma, in esadecimale minuscolo. - Accetta la richiesta solo se il risultato è uguale a
v1(confronta in tempo costante) e setrisale al massimo a pochi minuti prima.
In Come collegarlo, Verifica la firma (Node.js) mostra questi passaggi sotto forma di codice, con Copia codice. Nuova chiave sostituisce subito la chiave, quindi aggiorna la tua verifica subito dopo.
Nuovi tentativi, registro e pausa
Rispondi con uno stato 2xx entro 10 secondi. Altrimenti riproviamo più tardi, fino a 6 tentativi in tutto nell'arco di circa un giorno. I reindirizzamenti non vengono seguiti, e una risposta 410 interrompe i tentativi. Il Registro delle consegne mostra gli ultimi 50 messaggi con la risposta del tuo endpoint, e Reinvia ne invia di nuovo uno.
Dopo 20 consegne non riuscite di fila, mettiamo in pausa il webhook (In pausa dopo errori) e avvisiamo via email i proprietari dello spazio di lavoro. Correggi l'endpoint, riattiva il webhook e reinvia dal registro ciò che ti serve. Puoi anche mettere in pausa un webhook con il suo interruttore: gli eventi che si verificano mentre è in pausa non vengono inviati in seguito. Senza Pro, i webhook restano ma non inviano nulla.
Esiste un'API?
Sì, con Pro. I webhook avvisano il tuo sistema quando succede qualcosa; l'API REST gli permette di agire: caricare e inviare documenti, e recuperare il loro stato, il PDF firmato e l'audit trail. Inizia da Usare l'API (in inglese), oppure consulta tutti gli endpoint nella documentazione dell'API (in inglese).