Creazione di webhook per interagire con sistemi di terzi

Quale piano sto usando?

Anteprima: Centro amministrativo > App e integrazioni > Azioni e webhook > Webhook

Un webhook invia una richiesta HTTP a un URL specificato in risposta a un’attività in Zendesk Support. Ad esempio, puoi configurare un webhook per inviare richieste quando un utente viene eliminato o viene creato un nuovo ticket.

Gli sviluppatori web in genere usano i webhook per richiamare un comportamento in un altro sistema. Ad esempio, puoi usare i webhook per:

• Avvisare il tuo team in Slack quando viene creato un ticket urgente
• Passare i dettagli del ticket al team responsabile della documentazione in Asana dopo che un ticket viene risolto
• Notificare al tuo servizio di back-end un evento ticket importante

Devi essere un amministratore o un agente con un ruolo personalizzato e con una specifica autorizzazione alla creazione di webhook. Gli account di prova hanno un limite di 10 webhook e un limite di 60 chiamate al minuto.

Questo articolo include i seguenti argomenti:

• Informazioni sui webhook
• Creazione di un webhook
• Test di un webhook

Informazioni sui webhook

Esistono due modi per collegare un webhook alle attività in Zendesk Support:

• Iscrivi il webhook a uno o più eventi Zendesk. Usa questo metodo di connessione per inviare richieste in base a organizzazione, utente, disponibilità degli agenti, centro assistenza o attività della community. Per un elenco dei tipi di eventi supportati, consulta Tipi di eventi webhook nella guida di riferimento API.
• Connetti il webhook a un trigger o a un’automazione. Usa questo metodo di connessione per inviare richieste in base alle attività dei ticket.

Un webhook iscritto a un evento Zendesk non può connettersi a un trigger o a un’automazione. Allo stesso modo, un webhook connesso a un trigger o a un’automazione non può iscriversi agli eventi Zendesk. Non puoi cambiare il metodo di connessione di un webhook esistente.

Importante: È stato fatto il possibile per fornire agli utenti gli eventi webhook quasi in tempo reale per le azioni in Zendesk. Tuttavia, a volte si verifica un ritardo.

Iscrizione agli eventi Zendesk

Un webhook iscritto a uno o più eventi Zendesk invia sempre le richieste usando il metodo POST HTTP. La richiesta include un payload JSON contenente i dati dell'evento. Non puoi cambiare il metodo HTTP o il payload della richiesta. Per ulteriori informazioni sugli schemi di payload degli eventi, consulta Tipi di eventi webhook nelle informazioni di riferimento sulle API.

Connessione a trigger o automazioni

Se un webhook è collegato a un trigger o a un’automazione, puoi personalizzare il metodo HTTP, il formato e il contenuto delle richieste del webhook. Quando crei il webhook, selezioni il metodo HTTP e il formato del corpo della richiesta. I webhook collegati a un trigger o a un’automazione supportano i seguenti formati del corpo delle richieste:

• JSON

• XML

• Corpo con codifica del modulo

Il contenuto della richiesta viene definito quando colleghi il webhook a un trigger o a un’automazione. Per i webhook che usano il metodo POST, PUT o PATCH HTTP con un formato di richiesta JSON o XML, il contenuto è il payload della richiesta. I webhook che usano altri metodi o formati HTTP non includono il payload della richiesta. In alternativa, puoi aggiungere parametri URL personalizzati come array di due stringhe chiave-valore. Quando definisci il payload o i parametri URL della richiesta, puoi usare qualsiasi segnaposto di contenuto disponibile per inserire i dati di ticket nella richiesta.

Il payload del webhook o i parametri URL della richiesta devono essere inferiori a 256 KB.

Ordinamento e ripetizioni dei webhook

Quando un evento, un trigger o un’automazione richiama un webhook, lo mette in coda per l’esecuzione del lavoro webhook, ma in realtà non lo esegue immediatamente. Poiché i lavori webhook vengono eseguiti in modo indipendente, non vi è alcuna garanzia che i webhook vengano eseguiti in un ordine particolare.

Le richieste webhook vengono ripetute automaticamente fino a tre volte se l’endpoint restituisce determinati codici di risposta HTTP. A differenza delle destinazioni, varie richieste non riuscite consecutive non disattivano i webhook. Per ulteriori informazioni ed esempi di scenari di ripetizione, consulta Monitoraggio dei webhook nella documentazione per sviluppatori.

Creazione di un webhook

Puoi creare un webhook nel Centro amministrativo.

Per creare un webhook

1. Nel Centro amministrativo, fai clic su App e integrazioni nella barra laterale, quindi seleziona Azioni e webhook > Webhook.
2. Fai clic su Crea webhook.
   

   • Per iscrivere il webhook a uno o più eventi Zendesk, seleziona Eventi Zendesk e uno o più tipi di eventi dal menu a discesa.
   • Per collegare il webhook a un trigger o a un’automazione, seleziona Trigger o Automazione.
3. Fai clic su Avanti.
4. Inserisci un nome e una descrizione per il webhook.
5. Inserisci l’ URL dell’endpoint usato per l’integrazione con il servizio o il sistema di terzi. Consulta Endpoint di webhook.

   Quando configuri un webhook per l’integrazione con una terza parte, potrebbe essere necessario consultare la documentazione di quest’ultima.

6. Seleziona il Metodo di richiesta e il Formato della richiesta del webhook.
7. Seleziona il metodo di autenticazione per il webhook e fornisci le informazioni aggiuntive necessarie. Consulta Autenticazione del webhook.
8. (Facoltativo) Fai clic su Aggiungi intestazione per aggiungere un’intestazione personalizzata, quindi inserisci un nome e un valore per l’intestazione. Per aggiungere un massimo di altre quattro intestazioni, fai clic su Aggiungi un’altra intestazione. Consulta Intestazioni webhook personalizzate.
   Nota: Non inserire informazioni sensibili nelle intestazioni personalizzate.
9. (Facoltativo) Fai clic su Test webhook per assicurarti che funzioni come previsto.
10. Fai clic su Crea webhook per creare il webhook.
11. Per i webhook di automazione e trigger, devi connettere il webhook a un trigger o a un’automazione. Consulta Collegare il webhook a un trigger o un’automazione di Support. Dopo aver collegato il trigger o l’automazione, torna alla pagina Crea webhook e fai clic su Termina configurazione.

Dopo aver creato il webhook, puoi visualizzarne i dettagli, gli abbonamenti e le attività nella pagina Webhook nel Centro amministrativo. Consulta Gestione dei webhook.

Endpoint di webhook

I webhook inviano richieste all’URL dell’endpoint specificato al momento della creazione. L’URL dell’endpoint usa il seguente formato: https://www.yourdomain.com/path.

Sebbene non sia obbligatorio, si consiglia l’uso del protocollo HTTP sicuro (HTTPS). Fornendo un URL dell’endpoint sicuro, puoi abilitare l’autenticazione e passare i dati in modo sicuro.

Intestazioni webhook personalizzate

Le intestazioni personalizzate consentono di includere ulteriori informazioni nella richiesta inviata dal webhook e possono semplificare la connessione ad alcuni servizi di terzi che hanno requisiti univoci per le intestazioni dei webhook. Tieni presente i seguenti requisiti e limitazioni per le intestazioni personalizzate:

• Per usare le intestazioni personalizzate, devi usare un URL dell’endpoint sicuro (HTTPS).
• Non includere credenziali di autenticazione o altre informazioni sensibili nelle intestazioni personalizzate. Usa invece i metodi di autenticazione supportati.
• I nomi delle intestazioni devono essere univoci e non possono contenere più di 128 caratteri. Tutti i caratteri alfanumerici ASCII statunitensi sono supportati, oltre ai simboli seguenti: !, #, $, %, &, ', *, +, -, ., ^, _, `, |, e ~.
• I valori delle intestazioni possono avere una lunghezza massima di 1.000 caratteri e supportare tutti i caratteri ASCII statunitensi da 0 x 20 a 0 x 7 E.
• Le seguenti intestazioni non sono supportate:
  • accept-charset
  • accept-encoding
  • connection
  • content-encoding
  • content-length
  • content-md5
  • content-type
  • date
  • expect
  • forwarded
  • host
  • keep-alive
  • max-forwards
  • origin
  • proxy-authenticate
  • referer
  • server
  • te
  • trailer
  • transfer-encoding
  • upgrade
  • user-agent
  • via
  • www-authenticate
  • zendesk-api-version
  • zendesk-ep
• Inoltre, le intestazioni non possono iniziare con i seguenti prefissi:
  • access-control
  • x-amzn
  • x-apigw
  • x-datadog
  • x-envoy
  • x-forwarded
  • x-zendesk

Autenticazione di un webhook

Se il webhook è integrato con un endpoint sicuro, sono disponibili tre opzioni per autenticare il webhook e i dati che invia. Ti consigliamo di fare riferimento alla documentazione di terzi sui requisiti di autenticazione del tuo endpoint o di collaborare con uno sviluppatore del tuo team per determinare il metodo di autenticazione corretto per il tuo webhook.

• Nessuna richiesta: nessuna autenticazione configurata o richiesta.
• Chiave API: usa una chiave API per autenticare il webhook.
• Autenticazione base: usa un nome utente e una password per autenticare il webhook.
• Token portatore: usa un token di accesso OAuth per autenticare il webhook.

Se gli sviluppatori richiedono ulteriori informazioni sull’autenticazione dei webhook, consulta Sicurezza e autenticazione dei webhook.

Per maggiore sicurezza, puoi anche verificare la firma del webhook. Per maggiori informazioni, consulta Verifica dell’autenticità del webhook.

Collegamento di un webhook a un trigger o a un’automazione

Per richiamare un trigger e un webhook di automazione, devi prima collegarli a un trigger o a un’automazione. I trigger e le automazioni specificano le circostanze in cui il webhook deve essere richiamato.

Per collegare un webhook a un trigger di Support

1. Nel Centro amministrativo, fai clic su Oggetti e regole nella barra laterale, quindi seleziona Regole aziendali > Trigger.
2. Crea un nuovo trigger o modificane uno posizionando il cursore del mouse sull’icona delle opzioni () e facendo clic su Modifica.
3. In Azioni, fai clic su Aggiungi azione. Seleziona Notifica webhook e quindi il tuo webhook.
4. Inserisci il payload o i parametri URL della richiesta del webhook, a seconda del formato della richiesta del webhook. Il payload o i parametri devono essere inferiori a 256 KB.
5. Fai clic su Salva.

Per collegare un webhook a un'automazione di Support

1. Nel Centro amministrativo, fai clic su Oggetti e regole nella barra laterale, quindi seleziona Regole aziendali > Automazioni.
2. Crea una nuova automazione o modificane una esistente posizionando il cursore del mouse sull’icona delle opzioni () e facendo clic su Modifica.
3. In Esegui queste azioni, fai clic sull'icona Aggiungi azione (). Seleziona Notifiche: Notifica webhook e quindi seleziona il webhook.
4. Inserisci il payload o i parametri URL della richiesta del webhook, a seconda del formato della richiesta del webhook. Il payload o i parametri devono essere inferiori a 256 KB.
5. Fai clic su Invia.

Test di un webhook

Nel Centro amministrativo hai la possibilità di testare il webhook con diverse origini eventi e richieste. Oltre ad accedere ai webhook esistenti specificamente per i test, puoi anche testare il webhook durante la creazione o la modifica.

Per testare un webhook

1. Nel Centro amministrativo, fai clic su App e integrazioni nella barra laterale, quindi seleziona Azioni e webhook > Webhook.
2. Trova il webhook nell’elenco, fai clic sull’icona del menu delle opzioni () nella riga del webhook, quindi fai clic su Testa webhook.
3. Nel pannello Test webhook, seleziona un evento da testare. Questa è una richiesta di esempio che puoi usare per testare l’URL dell’endpoint.
4. Inserisci i dettagli della richiesta di test (corpo, parametri o intestazioni della richiesta).
5. Fai clic su Invia test. La risposta è visibile nel pannello sotto la richiesta di test.