POST che Gestione Sala invia a un indirizzo HTTPS quando accade un evento in sala. Il webhook parte dall’azione Avvisa SQUADD di un’automazione: l’automazione decide quale evento e in quali condizioni, la consegna porta l’evento nella busta descritta qui.
Destinazione
L’azione Avvisa SQUADD indica dove consegnare in uno di questi modi:
Un’azione senza indirizzo e senza destinazione usa la destinazione principale del locale, cioè la registrata per prima. Se non esiste o è spenta, la consegna fallisce e l’esito compare nello storico dell’automazione.
L’indirizzo scritto nell’azione deve essere HTTPS. Ogni indirizzo deve risolvere a un IP pubblico: un indirizzo che risolve a una rete interna non riceve la richiesta. Il controllo si ripete a ogni tentativo.
Richiesta
La consegna riesce se il destinatario risponde
2xx entro 10 secondi. Una risposta 3xx è un fallimento: i redirect non vengono seguiti.
Busta
data.reservation è la prenotazione al momento dell’invio, non al momento dell’evento: un webhook inviato dopo un’attesa riporta orario e stato correnti. GET /events restituisce invece i dati al momento dell’evento; updatedAt indica quale delle due versioni è più recente.
Catalogo degli eventi
Per
guest_profile_changed, reason vale guest_created, profile_changed o service_tags_changed.
Le prenotazioni importate con POST /imports/reservations non generano eventi. Le organizzazioni di prova non inviano webhook.
Firma
La firma è un HMAC-SHA256 calcolato sul segreto e su questa stringa, quattro righe separate da\n:
X-Gestionesala-Signature con il prefisso v1=. Il timestamp è parte della stringa firmata: una richiesta ripetuta con un timestamp diverso non verifica.
Segreto
- Destinazione registrata: ogni destinazione ha il proprio segreto, versionato.
POST /webhook-endpoints/{id}/rotate-secretgenera la versione successiva e la restituisce una sola volta. - Indirizzo nell’azione: la consegna è firmata con il segreto dell’organizzazione, che coincide con la versione
0di ogni destinazione.
overlapMinutes minuti (predefinito: un giorno), l’header contiene due firme separate da virgola: v1=<nuova>,v1=<precedente>. Una firma valida è sufficiente. Aggiorna il segreto nel destinatario entro la scadenza della versione precedente.
Verifica
- Leggi il corpo come byte grezzi, prima di qualsiasi parsing JSON.
- Rifiuta la richiesta se
X-Gestionesala-Timestampdista più di 5 minuti dall’ora corrente. - Calcola la firma attesa sulla stringa
v1\n<timestamp>\n<idempotency-key>\n<corpo>. - Confronta la firma attesa con ciascuna firma dell’header, a tempo costante.
- Se
X-Gestionesala-Idempotency-Keyè già stata elaborata, rispondi200senza rielaborare.
Ritentativi
Una consegna fallita (errore di rete, timeout, risposta diversa da2xx) viene ritentata con attese crescenti. Corpo, firma e X-Gestionesala-Idempotency-Key non cambiano fra i tentativi; cambia solo X-Gestionesala-Timestamp, con la firma ricalcolata.
Dopo il quinto tentativo fallito, la consegna passa a
discarded ed entra nella coda di scarto. Disattivare o archiviare l’automazione annulla anche le consegne in attesa di un ritentativo.
Consegne e coda di scarto
Una consegna ancora
pending non si può rispedire: la risposta è 409. In GET /webhook-deliveries il corpo di ogni consegna è filtrato con gli scope della chiave: senza guests:read i dati dell’ospite sono ridotti all’id, senza reservations:read (o events:read) la prenotazione è null.
