Webhook
Gli articoli della guida potrebbero non essere del tutto accurati: aggiornamenti frequenti e traduzione automatica possono renderli non allineati all'app. In caso di dubbi, contatta l'assistenza.
In questa pagina
Un webhook avvisa il suo sistema nel momento in cui succede qualcosa in EventMann, così non deve continuare a chiedere. EventMann invia una richiesta HTTPS a un indirizzo che lei sceglie ogni volta che si verifica un evento sottoscritto: un ordine viene confermato, un ordine viene rimborsato, un evento va online. I webhook si trovano nella scheda Webhook di Integrazioni nella barra laterale.
- Apra Integrazioni e clicchi sulla scheda Webhook.
- Clicchi su Aggiungi webhook per creare un endpoint.
- La colonna Stato mostra Attivo o Disattivato, con il codice HTTP dell'ultimo tentativo.
- Un endpoint disattivato offre Riattiva.
Aggiungere un endpoint
- Assegni un Nome, per uso proprio.
- Inserisca l'URL dell'endpoint, un indirizzo web pubblico che accetti una richiesta POST.
- Selezioni gli eventi che desidera sotto Iscriviti agli eventi. Ne è richiesto almeno uno.
- Clicchi su Aggiungi webhook. Viene creata per lei una chiave segreta di firma di 64 caratteri.
Eventi che può scegliere
Il modulo elenca quindici eventi, e ciascuno di essi viene inviato:
| Evento | Inviato quando |
|---|---|
booking.created | Un ordine viene creato: al checkout per gli ordini gratuiti e quelli con richiesta di approvazione, al passaggio del pagamento per quelli a pagamento. |
booking.confirmed | Un ordine viene confermato: pagato, gratuito o inserito a mano. |
payment.received | Un pagamento viene accreditato. Viene inviato insieme a booking.confirmed, anche per gli ordini gratuiti. |
booking.cancelled | Un ordine viene annullato: dall'acquirente, da lei o dal suo team, oppure dal supporto di EventMann. cancelled_by indica chi (attendee, organizer o admin). |
booking.refunded | Un ordine viene rimborsato per intero. |
payment.refunded | Un rimborso viene accreditato, anche quelli parziali. Uno per rimborso, con il suo importo. |
event.created | Un evento viene creato, comunque sia stato realizzato (procedura guidata, copia, serie ricorrente). |
event.updated | I dettagli di un evento cambiano: titolo, descrizione, immagine, date, sede o indirizzo, link online, periodo di vendita, visibilità. changed elenca i campi. Un cambio di stato non è un aggiornamento; ha eventi propri. |
event.published | Un evento va online. |
event.cancelled | Lei annulla un evento. |
ticket.checked_in | Un biglietto viene ammesso all'ingresso: scansionato, inserito a mano, registrato in blocco, sincronizzato da uno scanner offline oppure venduto e ammesso alla biglietteria. Il check-out di un biglietto e la segnalazione di un mancato ingresso non lo inviano, e non lo invia nemmeno l'azione in blocco Registra ingresso nell'elenco Ordini, che segna interi ordini come arrivati senza una scansione all'ingresso. |
staff.assigned | Qualcuno diventa membro dello staff di un evento: lei approva la sua candidatura, oppure accetta un invito per quell'evento. |
staff.checked_in | Un membro dello staff registra l'inizio di un turno. |
vendor.assigned | Lei assegna un fornitore a un evento. |
vendor.invoice_submitted | Un fornitore invia una fattura per un incarico. |
Non ci sono eventi di pagamento. Stripe accredita le vendite dei biglietti direttamente sul suo conto, e EventMann non crea né vede quei pagamenti.
Come appare una consegna
Ogni consegna è una richiesta POST con un corpo JSON di questa forma: event (il nome), data (i dettagli), timestamp e delivery_id. I dati di booking.confirmed contengono l'id dell'ordine, il riferimento, lo stato, il totale, il nome e l'indirizzo e-mail dell'acquirente, l'id dell'evento e l'ora della conferma. booking.created aggiunge il titolo dell'evento e riporta invece l'ora della creazione. payment.received contiene l'id della prenotazione, l'importo, il gateway, l'id della transazione e l'ora.
La richiesta contiene tre intestazioni: X-Webhook-Event, X-Webhook-Delivery-Id e X-Webhook-Signature. La firma è un HMAC-SHA256 del corpo grezzo della richiesta in formato esadecimale, calcolato con la chiave segreta di firma del suo endpoint. Lo ricalcoli dal suo lato a partire dal corpo grezzo e lo confronti prima di fidarsi di un carico dati.
Verificare un endpoint
- Clicchi su Invia test per inviare un
pingdi prova al suo indirizzo e vedere subito il risultato. - Eventi sottoscritti mostra ciò che l'endpoint riceve. Usi Modifica per cambiare nome, indirizzo o eventi.
- La Chiave segreta di firma è nascosta; clicchi su Mostra per visualizzarla.
- Consegne recenti elenca gli ultimi tentativi con evento, stato, codice HTTP, durata e ora. Vedi tutto ne mostra altri.
Nuovi tentativi, errori e disattivazione automatica
- Viene considerata consegnata solo una risposta 2xx. Un reindirizzamento o qualunque altra risposta è un errore; i reindirizzamenti non vengono seguiti.
- Una consegna non riuscita viene ritentata fino a cinque volte, con attese di 10, 30 e poi 60 secondi tra un tentativo e l'altro.
- Quando falliscono tutti i tentativi per un evento, il contatore di errori dell'endpoint aumenta di uno. Dieci errori in un'ora sospendono l'invio a quell'endpoint per cinque minuti; le consegne attendono la fine della sospensione.
- Se si attiva la sospensione, o se il contatore di errori supera dieci, l'endpoint viene disattivato e lei riceve una notifica che lo indica.
- Un indirizzo che punta a una rete privata o interna viene rifiutato al momento del tentativo di consegna. Il test mostra «Bloccato», e una consegna reale disattiva l'endpoint.
- La cronologia delle consegne viene conservata per 30 giorni.
- Un endpoint disattivato mostra Questo endpoint è disattivato con il motivo.
- Risolva il problema sul suo ricevitore, poi clicchi su Riattiva. Il contatore di errori viene azzerato; indirizzo e chiave segreta restano invariati. Modificare nome o indirizzo non riattiva l'endpoint.
- Riprova su una consegna non riuscita invia di nuovo quell'evento come nuova consegna ai suoi endpoint attualmente attivi che lo sottoscrivono. Sono compresi gli altri suoi endpoint, quindi potrebbero riceverlo due volte.
Da sapere
- L'invio dei webhook usa una coda propria, così un ricevitore lento non rallenta prenotazioni o e-mail dei biglietti.
- Deselezionare un evento lo interrompe senza avviso. Non riceve alcuna comunicazione che ha smesso di riceverlo.
- Se collega uno strumento come Zapier con un token API di EventMann, le sottoscrizioni che crea compaiono anche qui, con il nome dell'evento.
- I webhook inviano al suo server il nome e l'indirizzo e-mail dell'acquirente di ogni ordine. Si assicuri che l'indirizzo sia suo e che lei sia autorizzato a trattare quei dati.
Risoluzione dei problemi
- Le consegne si sono interrotte e non vedo alcun errore — apra l'endpoint. Se è disattivato, risolva il problema sul ricevitore e clicchi su Riattiva.
- La firma non corrisponde mai — calcoli l'hash del corpo grezzo esatto, non di una copia ricodificata, con la chiave segreta dalla pagina dell'endpoint, e confronti il testo esadecimale.
- Il test funziona ma gli eventi reali non arrivano — verifichi che l'evento sia selezionato su questo endpoint, e che ciò che è accaduto corrisponda alla colonna «Inviato quando» della tabella.
- Ricevo lo stesso evento due volte — ha premuto Riprova, oppure ha due endpoint che lo sottoscrivono. Usi l'id di consegna per ignorare i duplicati.