Ricevere gli eventi di Drime Sign con i webhook

Un webhook fa sì che Drime chiami il tuo server ogni volta che succede qualcosa alle tue richieste di firma. Ogni chiamata è una POST JSON, firmata con un secret perché il tuo server possa verificare che arrivi da Drime.

#Aggiungere un webhook

1. Apri Impostazioni > Sviluppatori > Webhook.

   Da Firma, puoi anche fare clic su Preferenze, aprire la scheda Webhook, poi Apri le impostazioni Sviluppatori.

2. Fai clic su Aggiungi un webhook.

3. In URL dell'endpoint, inserisci l'indirizzo del server che riceve le chiamate.

4. Sotto Eventi, imposta su Attivato ogni evento che vuoi ricevere, poi fai clic su Crea il webhook.

   Webhook creato lo conferma.

5. Copia subito il secret, poi fai clic su Fatto.

   Secret del webhook: copialo adesso: viene mostrato una sola volta. Conservalo in un posto sicuro.

#Gli eventi

#Cosa invia Drime

Ogni chiamata contiene queste intestazioni:

• X-Drime-Event: l'evento, ad esempio envelope.completed;

• X-Drime-Delivery: il numero della consegna;

• X-Drime-Signature: sha256= seguito dall'HMAC SHA-256 del corpo grezzo, calcolato con il tuo secret.

Il corpo JSON contiene event_type, event_uuid, timestamp e data, il documento interessato con i suoi firmatari. La sezione Webhook mostra un esempio completo in Esempio di richiesta e verifica della firma.

Una consegna può arrivare più di una volta: usa event_uuid per elaborare ogni evento una sola volta.

#Verificare la firma

Calcola l'HMAC SHA-256 del corpo grezzo della richiesta con il tuo secret, poi confrontalo con l'intestazione X-Drime-Signature. Ad esempio, in Node.js:

import crypto from 'node:crypto';

function isFromDrime(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return header.length === expected.length && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Usa il corpo esattamente come lo ricevi, prima di qualsiasi parsing JSON.

#Testare e seguire le consegne

• Invia un test invia un evento di prova: Evento di test in coda: controlla il log delle consegne.

• Consegne elenca ogni chiamata con il suo stato: Successo, In sospeso o Non riuscito. Invia di nuovo ripete una consegna.

• Se il tuo server non risponde o risponde con un errore, Drime riprova, fino a 10 tentativi in circa 34 ore.

• L'interruttore Attivato / Disattivato mette in pausa un webhook senza eliminarlo: Webhook in pausa lo conferma, e Webhook attivato quando lo riattivi.

#Cambiare il secret o eliminare il webhook

• Cambia il segreto crea un nuovo secret. L'app avvisa: Rigenerare il secret? Il tuo secret attuale smetterà di funzionare subito. Aggiorna subito il tuo server.

• Elimina rimuove il webhook: Eliminare questo webhook e tutta la sua cronologia delle consegne?

#Se non funziona

#Passi successivi

• Creare un'app o collegare dei webhook

• Creare un token API

• Cosa contiene il certificato di audit di un documento firmato