API e Webhook

GUIDA: Webhook, ricevi le registrazioni in tempo reale

Di: Diego Betancor, CTO · Ingegnere informatico ed economista aziendale

I webhook avvisano il tuo sistema nel momento in cui gli ospiti di una prenotazione completano la registrazione, per aggiornare il PMS, avviare messaggi o dare accesso senza interrogare nulla. Per creare prenotazioni dal tuo software, consulta la guida all’API prenotazioni.

Notifiche disponibili

Ricevi notifiche sulla registrazione delle tue prenotazioni; ad esempio, quando la registrazione di una prenotazione è completata. Ecco come appare una notifica:

{
  "id": "0192f3a4-…",
  "type": "guest_registration.completed",
  "version": 1,
  "data": {
    "property_id": "prop_…",
    "property_name": "Casa Sol",
    "booking": { "reference": "HMABC123", "check_in": "2026-11-10", "check_out": "2026-11-12" },
    "guests": { "registered": 3, "expected": 4 },
    "complete": true,
    "completed_at": "2026-10-15T09:59:00.000Z"
  }
}

La notifica non include documenti d’identità, date di nascita, firme, nomi, e-mail né telefoni.

Configurazione

  1. Vai su Integrazioni → API → Webhook.
  2. Scegli la struttura (ogni alloggio ha la sua destinazione).
  3. Nel pannello webhook, aggiungi l’URL del tuo server e seleziona gli eventi da ricevere.
  4. Copia il segreto di firma per verificare le notifiche sul tuo server.

Gestione dal pannello

Dal pannello puoi:

  • Aggiungere, modificare, mettere in pausa ed eliminare indirizzi di destinazione.
  • Scegliere gli eventi a cui si iscrive ciascuno.
  • Vedere la cronologia delle consegne: stato, codice di risposta, tentativi e contenuto di ogni notifica.
  • Reinviare manualmente una notifica specifica.
  • Reinviare le notifiche non riuscite: recupera in una volta tutto ciò che non è arrivato al tuo server durante un’interruzione.
  • Inviare eventi di prova per verificare l’integrazione (portano "test": true e dati fittizi).
  • Vedere e ruotare il segreto di firma. Dopo la rotazione, il precedente resta valido per 24 ore, così puoi aggiornare il server senza perdere notifiche.

Tentativi automatici

Se il tuo server non risponde con un codice 2xx, la notifica viene reinviata automaticamente con attese crescenti. Se un indirizzo fallisce in modo continuo per diversi giorni, viene disattivato; puoi riattivarlo dal pannello e reinviare ciò che è in sospeso.

Verificare la firma

Ogni notifica include intestazioni con l’identificativo della notifica, il timestamp e la firma. Verifica sempre la firma con il segreto del tuo webhook e il corpo non modificato. Se hai bisogno di aiuto per implementarla, scrivici da Contatto.

Rifiuta le notifiche con un timestamp vecchio per evitare reinvii malevoli.

Buone pratiche

  • Rispondi subito con un 2xx ed elabora la notifica dopo.
  • Gestisci i duplicati: la consegna può ripetersi. Usa il campo id dell’evento per ignorare quelli già elaborati.
  • Non dipendere dall’ordine di arrivo.
  • Ignora gli eventi di prova ("test": true) in produzione.
  • Usa sempre HTTPS per l’indirizzo di destinazione.