Deskhero
Italiano
Inizia gratis

← Back to articles

Cosa fanno i webhook dell’helpdesk e perché sono importanti

Cosa fanno i webhook dell’helpdesk e perché sono importanti

Un webhook dell’helpdesk è una richiesta HTTP in uscita che invia gli eventi dei ticket a un altro sistema non appena si verificano. Può attivare avvisi, automazioni o sincronizzazioni dei dati senza dover eseguire frequenti polling. Un’integrazione affidabile richiede comunque una configurazione accurata: verifica ogni richiesta, conferma rapidamente le consegne e testa l’endpoint prima di affidargli il traffico di produzione.

In breve:

  • I webhook possono fornire aggiornamenti sui ticket con meno ritardo e meno chiamate API rispetto al polling frequente.
  • La configurazione di solito prevede un endpoint HTTPS pubblico, una sottoscrizione agli eventi, la verifica delle richieste e test con eventi rappresentativi.
  • I controlli di sicurezza dipendono dal provider, ma includono comunemente HTTPS, verifica tramite firma o token, rotazione dei segreti ed elaborazione con il principio del minimo privilegio.
  • I ricevitori devono tollerare eventi duplicati o fuori sequenza utilizzando un’elaborazione idempotente e riconciliando i dati con lo stato corrente.
  • Deskhero attualmente non invia webhook in uscita. La sua API REST può essere interrogata tramite polling quando un’integrazione personalizzata necessita dei dati dei ticket.

Indice

Come funzionano i webhook dell’helpdesk: evento, POST, payload

Un webhook dell’helpdesk inizia con un evento. Qualcuno apre un ticket, un Utente ne modifica lo stato, un cliente risponde oppure cambia la priorità. Se la piattaforma offre un webhook per quell’evento e ti sei iscritto, la piattaforma invia una richiesta HTTP all’URL registrato. A differenza del polling eseguito secondo una pianificazione fissa, il ricevitore non deve continuare a chiedere se è cambiato qualcosa. I payload dei webhook sono spesso in formato JSON, anche se formato e campi esatti dipendono dal provider.

Diagramma dei campi di un payload JSON di un webhook

Un payload relativo alla creazione di un ticket potrebbe includere l’ID del ticket, lo stato, la priorità, i dati del richiedente e le informazioni sulla causa dell’evento. Non dare per scontato che questi campi esistano o mantengano sempre la stessa struttura. Considera lo schema corrente degli eventi del provider come fonte autorevole e convalida i payload prima di utilizzarli.

La differenza pratica rispetto al polling riguarda i tempi e il controllo. Un webhook può notificare il tuo ricevitore poco dopo un evento, mentre un sistema di polling rileva i cambiamenti alla successiva esecuzione. Il polling è spesso più semplice quando gli aggiornamenti non sono urgenti. I webhook sono utili quando è importante ridurre il ritardo e il provider supporta gli eventi e i controlli di sicurezza necessari.

Quali sono i migliori casi d’uso per i webhook dell’helpdesk?

I webhook sono più utili quando un altro sistema deve reagire rapidamente a un evento relativo a un ticket. Alcuni esempi comuni:

  • Avvisi sui canali. Un ticket nuovo o urgente può attivare una notifica in uno strumento di collaborazione, se l’helpdesk genera quell’evento e l’integrazione ricevente lo supporta.
  • Aggiornamenti del CRM. Alcune attività dei ticket possono essere copiate nella scheda di un cliente, così i team di supporto e vendite dispongono del contesto rilevante.
  • Attivazione delle escalation. Un evento urgente può creare un incidente o un avviso in un sistema per la gestione dei turni di reperibilità.
  • Acquisizione per l’analisi. Gli eventi dei ticket possono alimentare una coda o una pipeline di dati per la reportistica successiva.
  • Coordinamento tra sistemi. Un evento relativo a un ticket può creare o aggiornare un’attività di lavoro correlata per un altro team.

Questi flussi di lavoro richiedono comunque un responsabile chiaro e una gestione degli errori. Un webhook è solo il meccanismo di consegna. Il sistema ricevente resta responsabile della convalida dell’evento, dell’applicazione delle regole aziendali e del recupero dei dati quando i servizi a valle non sono disponibili.

Come si configura un webhook dell’helpdesk?

Il processo esatto varia in base alla piattaforma, ma una configurazione tipica segue questi passaggi:

  1. Leggi la documentazione del provider. Conferma i tipi di evento disponibili, lo schema del payload, il metodo di autenticazione, il timeout, la politica di nuovi tentativi e le funzionalità dei registri di consegna.
  2. Rendi disponibile un endpoint HTTPS pubblico. Crea una route che accetti il formato delle richieste del provider. Molti sistemi webhook utilizzano richieste POST con JSON, ma la tua implementazione deve seguire il contratto documentato.
  3. Registra l’endpoint e gli eventi. Aggiungi l’URL tramite l’interfaccia di amministrazione o l’API della piattaforma, quindi iscriviti solo agli eventi necessari per la tua integrazione.
  4. Configura la verifica delle richieste. Se il provider fornisce un segreto di firma o un token di verifica, conservalo in un gestore di segreti o in una variabile d’ambiente protetta. Non inserirlo mai direttamente nel codice sorgente.
  5. Conferma rapidamente la ricezione. Restituisci la risposta di successo prevista prima di avviare elaborazioni lente a valle. La documentazione sui webhook di Stripe consiglia di rimandare l’elaborazione complessa a dopo che l’endpoint ha restituito una risposta positiva.
  6. Esegui i test prima della messa in produzione. Utilizza gli eventi di test del provider o un’area di lavoro di sviluppo. Uno strumento sicuro di inoltro può essere utile durante lo sviluppo locale, ma non esporre un servizio di sviluppo non protetto al traffico di produzione.
  7. Controlla i risultati delle consegne. Se il provider fornisce un registro delle consegne, usalo per confrontare gli eventi inviati con le risposte e i record di elaborazione del tuo ricevitore.

Una conferma rapida riduce la probabilità che un provider interpreti un ricevitore lento come una consegna fallita. Accodare l’evento verificato prima di procedere con l’elaborazione semplifica anche i nuovi tentativi del tuo sistema, senza dover chiedere al mittente di inviarlo nuovamente.

Come si protegge un endpoint webhook dell’helpdesk?

Un URL webhook è raggiungibile dall’esterno della tua rete, quindi il ricevitore non deve fidarsi di una richiesta soltanto perché è arrivata al percorso corretto.

Utilizza HTTPS con un certificato valido e una configurazione TLS attualmente supportata. Implementa quindi il meccanismo di verifica documentato dal provider. Può trattarsi di una firma HMAC, di un token di verifica, di firme asimmetriche o di un altro schema. La verifica della firma spesso richiede il corpo grezzo esatto della richiesta, quindi eseguila prima di analizzarlo o trasformarlo.

Proteggiti dai replay quando lo schema del provider supporta timestamp o ID evento univoci. Confronta le firme in tempo costante, rifiuta le richieste non valide ed evita di inserire segreti o dati personali nei registri dell’applicazione. Ruota i segreti quando possibile e mantieni una procedura di sovrapposizione documentata se, durante la rotazione, devono funzionare sia i vecchi sia i nuovi segreti.

Concedi al processore del webhook solo le autorizzazioni necessarie. Se il provider pubblica intervalli di indirizzi IP di origine stabili, una lista consentita può costituire un controllo aggiuntivo, ma non deve sostituire la verifica delle richieste. Applica con attenzione i limiti di frequenza, monitora gli errori e conserva solo i dati degli eventi necessari per il flusso di lavoro.

Diagramma panoramico su come proteggere un endpoint webhook dell’helpdesk

Come si testano e si esegue il debug dei webhook dell’helpdesk?

Inizia separando i problemi di consegna dai problemi di elaborazione. Verifica se il provider ha inviato l’evento, se la richiesta ha raggiunto il tuo endpoint, quale risposta ha restituito l’endpoint e se l’evento accettato ha completato l’elaborazione a valle.

  • Utilizza gli eventi di test forniti dal provider, quando disponibili, quindi testa eventi reali rappresentativi in un’area di lavoro non di produzione.
  • Registra un ID evento, il tipo di evento, l’orario di ricezione, il risultato della verifica, lo stato della risposta e l’esito dell’elaborazione. Oscura i segreti e riduci al minimo i dati personali memorizzati.
  • Utilizza il registro delle consegne della piattaforma per esaminare i codici di risposta e i nuovi tentativi. Zendesk documenta l’attività e i dettagli delle chiamate dei webhook per la risoluzione dei problemi del suo servizio webhook.
  • Confronta il registro delle consegne del provider con i registri del reverse proxy e dell’applicazione. Header mancanti o modifiche al corpo possono indicare una configurazione errata del middleware o del proxy.
  • Testa timeout, firme non valide, ID evento duplicati, servizi a valle non disponibili ed eventi consegnati in un ordine imprevisto.

Consiglio: Conserva una cronologia strutturata delle consegne sufficientemente dettagliata da consentire di tracciare gli errori, ma imposta un periodo di conservazione ed evita di registrare i payload grezzi, a meno che non siano realmente necessari e adeguatamente protetti.

Come si gestiscono gli eventi webhook duplicati o fuori sequenza?

Non dare per scontato che ogni evento venga consegnato esattamente una volta o che gli eventi arrivino sempre nell’ordine di creazione. Il comportamento delle consegne dipende dal provider e i nuovi tentativi possono produrre duplicati. La panoramica di Hookdeck confronta gli approcci alla consegna almeno una volta e esattamente una volta.

Rendi idempotenti i gestori. Quando un provider fornisce un ID evento stabile, registralo ed evita di applicare due volte la stessa operazione. Per i cambiamenti di stato, utilizza timestamp o valori di sequenza se il provider li definisce e recupera lo stato corrente della risorsa quando la correttezza è più importante dell’elaborazione di ogni transizione intermedia. Accoda il lavoro non riuscito con un numero limitato di tentativi e un backoff, quindi invia gli errori persistenti a una coda di messaggi non recapitabili consultabile o a un processo equivalente.

L’opzione API di Deskhero

Deskhero attualmente fornisce un’API REST con token bearer personali, ma non invia webhook in uscita. Un’integrazione che necessita dei dati dei ticket di Deskhero deve interrogare l’API a intervalli appropriati e rispettare il relativo limite di frequenza. Si tratta di un modello diverso dalla consegna degli eventi descritta sopra, quindi pianifica checkpoint, paginazione, deduplicazione e recupero dopo il fallimento di un’attività di polling.

Scegliere tra webhook e polling

Scegli in base al sistema con cui ti stai integrando, non partendo dal presupposto che ogni helpdesk supporti entrambi i modelli. I webhook possono ridurre il ritardo nel rilevamento, ma richiedono un ricevitore pubblico e una gestione accurata delle consegne. Il polling richiede una pianificazione e una logica per i checkpoint, ma può essere più semplice da gestire e riconciliare.

Deskhero

Deskhero trasforma una casella di posta Gmail o Microsoft 365 in un helpdesk condiviso, mantenendo l’indirizzo email aziendale esistente. Offre la sincronizzazione bidirezionale delle email, automazioni integrate per i ticket, bozze di risposta generate dall’AI e basate sulla conoscenza dell’area di lavoro e un’API REST per le integrazioni personalizzate. Le automazioni di Deskhero vengono eseguite quando vengono creati nuovi ticket; non sostituiscono i webhook in uscita. Gli utenti Shopify possono inoltre collegare l’integrazione Shopify per visualizzare in Deskhero le informazioni pertinenti sugli ordini e sui clienti. È disponibile una prova gratuita di 30 giorni senza carta di credito.

Dove approfondire gli standard dei webhook

Non esiste un unico standard per i webhook che faccia comportare ogni provider allo stesso modo. Utilizza la documentazione del tuo provider come riferimento autorevole per gli schemi degli eventi, la verifica, i nuovi tentativi e i timeout. La documentazione sui webhook di Notion offre un esempio concreto di verifica della sottoscrizione e consegna degli eventi.

Fonti

FAQ

Che cosa sono esattamente i webhook?

Un webhook è una richiesta HTTP che un sistema invia a un URL registrato dopo un evento definito. Contiene informazioni che consentono al sistema ricevente di decidere come reagire.

Quali sono gli svantaggi dell’utilizzo dei webhook?

I webhook richiedono un ricevitore sicuro e pubblicamente raggiungibile. L’integrazione deve inoltre tenere conto della verifica specifica del provider, dei nuovi tentativi, degli eventi duplicati, del possibile riordinamento, dei periodi di inattività, del monitoraggio e delle modifiche agli schemi degli eventi.

Che differenza c’è tra un webhook e un’API?

Un’API consente generalmente al tuo software di richiedere dati o attivare un’azione. Un webhook permette a un altro sistema di inviare un evento al tuo ricevitore. Molte integrazioni utilizzano entrambi: il webhook annuncia un cambiamento e l’API fornisce i dati aggiornati della risorsa.

Puoi fornirmi un esempio di webhook dell’helpdesk?

Un helpdesk che supporta i webhook in uscita potrebbe inviare un evento di creazione di un ticket al tuo ricevitore. Dopo aver verificato la richiesta, la tua integrazione potrebbe aggiungere una notifica al canale di un team o aggiornare una scheda nel CRM. Deskhero attualmente non invia webhook in uscita, quindi le integrazioni personalizzate con Deskhero devono interrogare la sua API REST.