Configurazione dei webhook per aggiornamenti in tempo reale di Sign.Plus

I webhook ti permettono di ricevere aggiornamenti in tempo reale sullo stato delle tue buste in Sign.Plus. Questo articolo ti guiderà attraverso il processo di configurazione e gestione dei webhook per la tua integrazione con Sign.Plus.

Passo 1: Crea un webhook

Per iniziare a ricevere aggiornamenti in tempo reale, devi prima creare un webhook in Sign.Plus. Ecco come fare:

1. Decidi un URL di destinazione dove desideri ricevere le notifiche webhook. Deve trattarsi di un endpoint sul tuo server configurato per gestire le richieste POST in entrata.
2. Scegli l'evento o gli eventi che desideri monitorare. Sign.Plus offre i seguenti eventi webhook:
   • envelope_completed

      - Quando una busta è completata

   • envelope_expired

      - Quando una busta è scaduta

   • envelope_declined

      - Quando una busta viene rifiutata

   • envelope_voided

      - Quando una busta viene annullata

3. Usa l'API di Sign.Plus per creare il webhook. Dovrai specificare il tuo URL di destinazione e l'evento o gli eventi che desideri monitorare.

Per informazioni dettagliate su come creare un webhook utilizzando l'API di Sign.Plus, consulta la documentazione dell'endpoint per la creazione di un webhook.

Passo 2: Gestisci le notifiche webhook

Una volta configurato il tuo webhook, Sign.Plus invierà richieste POST all'URL specificato ogni volta che si verificano gli eventi monitorati. Ecco cosa devi sapere sulla gestione di queste notifiche:

1. Metodo di richiesta: Tutte le notifiche webhook vengono inviate come richieste HTTP 

   POST

   .

2. Struttura del payload: Il payload del webhook è un oggetto JSON che contiene due sezioni principali:
   • hook

     : Contiene i metadati relativi al webhook stesso.

   • data

     : Contiene le informazioni relative alla busta che ha attivato l'evento.

3. Esempi di payload: Ecco alcuni esempi di payload per diversi eventi:

   // ENVELOPE_DECLINED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_declined",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_COMPLETED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_completed",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_EXPIRED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_expired",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_VOIDED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_voided",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
4. Gestione della notifica: Quando il tuo server riceve una notifica webhook:
   • Verifica il payload per assicurarti che sia una notifica webhook valida.
   • Estrai le informazioni rilevanti dal payload.
   • Esegui le azioni necessarie in base al tipo di evento (ad es. aggiornare il database, notificare gli utenti, attivare altri processi).

   • Invia una risposta 

     200 OK

      per confermare la ricezione del webhook.

I webhook di Sign.Plus verranno inviati solo dai seguenti indirizzi IP autorizzati:
34.65.253.117
34.65.146.131

Buone pratiche

1. Sicurezza: assicurati che il tuo endpoint webhook sia sicuro. Considera l'implementazione di un'autenticazione per l'URL del tuo webhook.
2. Idempotenza: progetta il gestore del webhook in modo che sia idempotente. Ciò significa che deve produrre lo stesso risultato anche se lo stesso webhook viene ricevuto più volte.
3. Gestione degli errori: implementa una gestione degli errori robusta nella logica di elaborazione dei tuoi webhook.

Seguendo questa guida, sarai in grado di configurare e gestire i webhook in modo efficace, permettendo alla tua applicazione di ricevere aggiornamenti in tempo reale sullo stato delle buste in Sign.Plus.