Impostazione di webhooks per gli aggiornamenti Sign.Plus in tempo reale

I Webhooks ti permettono di ricevere aggiornamenti in tempo reale sullo stato delle tue buste nel Sign.Plus. Questo articolo ti guiderà nel processo di impostazione e gestione dei webhooks per l'integrazione Sign.Plus.

Passo 1: Creare un webhook

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

1. Decidi l'URL di destinazione in cui vuoi ricevere notifiche webhook. Questo dovrebbe essere un endpoint sul tuo server impostato per gestire le richieste POST in arrivo.
2. Scegli l'evento o gli eventi che vuoi tracciare. 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 Sign.Plus per creare il webhook. È necessario specificare l'URL di destinazione e gli eventi che si desidera tracciare.

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

Passo 2: Gestire notfications webhook

Una volta impostato il tuo webhook, Sign.Plus invierà richieste POST all'URL specificato ogni volta che si verificano gli eventi tracciati. 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 Payload: Il payload webhook è un oggetto JSON contenente due sezioni principali:
   • hook: Contiene metadati sul webhook stesso.
   • dati: Contiene informazioni sulla busta che ha innescato l'evento.
3. Esempi di Payload: Ecco 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",
"evento": "envelope_completato",
"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",
"evento": "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",
"evento": "envelope_voided",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
4. Gestione delle notifiche: Quando il server riceve una notifica webhook:
   • Verificare il payload per assicurarsi che sia una notifica webhook valida.
   • Estrarre le informazioni pertinenti dal carico utile.
   • Eseguire tutte le azioni necessarie in base al tipo di evento (ad esempio, aggiornare il database, avvisare gli utenti, attivare altri processi).
   • Invia una risposta200 OKper confermare la ricezione del webhook.

Migliori pratiche

1. Sicurezza: Assicurati che il tuo endpoint webhook sia sicuro. Considera l'implementazione dell'autenticazione per il tuo URL webhook.
2. Idempotenza: Progetta il tuo gestore webhook per essere idempotente. Ciò significa che dovrebbe produrre lo stesso risultato anche se lo stesso webhook viene ricevuto più volte.
3. Error Handling: Implementa una gestione degli errori robusta nella tua logica di elaborazione del webhook.

Seguendo questa guida, sarai in grado di impostare e gestire efficacemente i webhook, consentendo alla tua applicazione di ricevere aggiornamenti in tempo reale sugli stati della busta nel Sign. lus.