Webhooks

I webhook consentono ai Suoi sistemi di essere avvisati nel momento esatto in cui succede qualcosa in EventMann — una prenotazione confermata, un biglietto con check-in effettuato, un pagamento erogato — invece di dover interrogare periodicamente per rilevare le modifiche. Si trovano nella stessa riga Integrazioni della barra laterale, nella scheda Webhooks.

Come aggiungere un endpoint

1. Vada su Integrazioni → Webhooks → Aggiungi
2. Assegni un nome e l'URL pubblico http(s) che dovrà ricevere le chiamate — un indirizzo privato o interno viene rifiutato categoricamente, sia qui sia ogni volta che un webhook viene effettivamente attivato
3. Selezioni i tipi di evento che desidera ricevere
4. Salvi. Un secret di firma di 64 caratteri viene generato automaticamente per Lei e mostrato mascherato; usi Mostra/Nascondi per rivelarlo una volta

Eventi a cui è possibile iscriversi

Evento	Si attiva quando
booking.created	una prenotazione viene avviata, prima del pagamento
booking.confirmed	una prenotazione viene confermata
booking.cancelled	una prenotazione viene annullata
booking.refunded	una prenotazione viene rimborsata
event.created	crea un nuovo evento
event.published	un evento diventa live
event.cancelled	un evento viene annullato
event.updated	i dettagli dell'evento cambiano
ticket.checked_in	un biglietto viene scansionato all'ingresso
payment.received	un pagamento viene regolato
payment.refunded	un pagamento viene rimborsato
payout.created	viene creato un pagamento agli organizzatori
payout.paid	un pagamento agli organizzatori viene erogato
staff.assigned	un membro dello staff viene assegnato al Suo evento
staff.checked_in	un membro dello staff effettua il check-in per un turno
vendor.assigned	un fornitore viene assegnato al Suo evento
vendor.invoice_submitted	un fornitore invia una fattura

Il funzionamento della consegna

Ogni chiamata è una POST di JSON strutturata così:

{"event":"booking.confirmed","data":{"id":1,"reference":"BK-ABC123","status":"confirmed","total":49.99,"currency":"USD","attendee_name":"Jane Doe","attendee_email":"jane@example.com","event_id":10,"confirmed_at":"2026-03-01T12:05:00Z"},"timestamp":"2026-03-01T12:05:00Z","delivery_id":"..."}

Insieme a essa riceverà un'intestazione X-Webhook-Event che indica il tipo di evento, un X-Webhook-Delivery-Id, e un'intestazione X-Webhook-Signature — un HMAC-SHA256 del corpo grezzo della richiesta, firmato con il secret mostrato nella pagina dell'endpoint. Lo ricalcoli allo stesso modo dal Suo lato e lo confronti prima di considerare attendibile un payload.

I nuovi tentativi e cosa succede se un ricevitore non risponde

• Una consegna viene tentata fino a 5 volte, con un'attesa di 10, poi 30, poi 60 secondi tra un tentativo e l'altro; solo una risposta 2xx conta come consegnata
• Una volta falliti tutti e 5 i tentativi per un evento, il contatore di errori dell'endpoint aumenta esattamente di uno — non una volta per tentativo
• 10 consegne fallite entro un'ora mobile mettono in pausa quell'endpoint per 5 minuti; se il contatore di errori supera mai 10, o se scatta quella pausa, l'endpoint si disattiva automaticamente e smette di ricevere qualsiasi cosa finché non lo corregge
• Riceverà una notifica in-app nel momento esatto in cui questo accade, con il nome dell'endpoint
• Un endpoint disattivato mostra un avviso "Questo endpoint è disattivato", con il motivo, sia nell'elenco degli endpoint sia nella sua pagina — modificarne il nome, l'URL o gli eventi non lo riattiva. Corregga ciò che non andava nel Suo ricevitore, poi usi il pulsante Riattiva; questo azzera il contatore di errori e toglie la pausa alla consegna, mantenendo lo stesso URL e lo stesso secret di firma
• La cronologia delle consegne — tipo di evento, stato HTTP, durata e orario — viene conservata per 30 giorni e poi eliminata automaticamente

Da sapere

• Test, nella pagina di un endpoint, invia un evento sintetico ping così può verificare il Suo ricevitore e la verifica della firma prima di iscriversi a qualcosa di reale
• Riprova su una consegna fallita reinvia quell'evento da zero ai Suoi endpoint attualmente attivi — è una nuova consegna, non una ripresa della catena di tentativi originale
• Gli invii dei webhook girano sulla propria coda, separata dal checkout e dalle email, così un ricevitore lento o guasto dal Suo lato non può rallentare le prenotazioni o le email dei biglietti
• Deselezionare un tipo di evento ne interrompe silenziosamente l'invio — non c'è alcun avviso che ha smesso di riceverlo

Risoluzione dei problemi

• Le consegne si sono fermate senza alcun errore visibile dal mio lato — apra l'endpoint e controlli il contatore di errori e lo stato; se risulta disattivato, corregga il Suo ricevitore e faccia clic su Riattiva
• La firma non corrisponde mai — calcoli l'hash sul corpo grezzo esatto della richiesta, non su una copia riserializzata, con il secret mostrato nella pagina dell'endpoint
• Il test riesce ma gli eventi reali non arrivano mai — verifichi che quel tipo di evento specifico sia selezionato su quell'endpoint; i tipi non sottoscritti semplicemente non vengono mai inviati

Vedi anche

• Integrazioni
• Ordini
• Check-in
• Pagamenti