# Ricevere gli eventi di Drime Sign con i webhook

Ricevi una notifica HTTP sul tuo server quando un documento viene inviato, visto, firmato, rifiutato o completato in Drime Sign, e verificane l'origine.

Aggiornato: 2026-10-21  
Fonte: https://drime.cloud/it/support/integrations-and-api/sign-webhooks

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.

![La finestra del nuovo webhook con l'URL dell'endpoint di un server dimostrativo e l'elenco degli eventi di Drime Sign](https://drime.cloud/media/01M5F06YR56KKN1FP1T6WCV3QW/8adc8de810cf-web-sign-webhook-create.png)

## Gli eventi

| Evento | Inviato quando |
| --- | --- |
| `envelope.sent` | Un documento viene inviato per la firma |
| `envelope.completed` | Tutti i firmatari hanno firmato |
| `envelope.declined` | Un firmatario ha rifiutato, quindi il documento è rifiutato |
| `signer.viewed` | Un firmatario ha aperto il documento |
| `signer.signed` | Un firmatario ha firmato |
| `signer.declined` | Un firmatario ha rifiutato |
| `template.created` | Viene creato un modello |

## 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:

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

| Cosa vedi | Cosa fare |
| --- | --- |
| **Inserisci l'URL dell'endpoint** | Inserisci l'indirizzo del tuo server prima di creare il webhook. |
| **Attiva almeno un evento** | Scegli almeno un evento sotto **Eventi**. |
| Le consegne restano **Non riuscito** | Controlla che il tuo server sia raggiungibile da internet e risponda con un codice di successo. Poi fai clic su **Invia di nuovo**. |
| Il tuo server rifiuta la firma | Calcola l'HMAC sul corpo grezzo, non sul JSON già elaborato, e usa il secret attuale. Dopo **Cambia il segreto**, quello vecchio non funziona più. |

## Passi successivi

- [Creare un'app o collegare dei webhook](https://drime.cloud/it/support/integrations-and-api/build-an-integration)
- [Creare un token API](https://drime.cloud/it/support/integrations-and-api/api-tokens)
- [Cosa contiene il certificato di audit di un documento firmato](https://drime.cloud/it/support/sign/audit-trail-and-certificate)