Skip to main content
Un webhook è una richiesta 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:
Il risultato, in esadecimale minuscolo, viaggia in 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-secret genera 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 0 di ogni destinazione.
Durante una rotazione, per 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

  1. Leggi il corpo come byte grezzi, prima di qualsiasi parsing JSON.
  2. Rifiuta la richiesta se X-Gestionesala-Timestamp dista più di 5 minuti dall’ora corrente.
  3. Calcola la firma attesa sulla stringa v1\n<timestamp>\n<idempotency-key>\n<corpo>.
  4. Confronta la firma attesa con ciascuna firma dell’header, a tempo costante.
  5. Se X-Gestionesala-Idempotency-Key è già stata elaborata, rispondi 200 senza rielaborare.

Ritentativi

Una consegna fallita (errore di rete, timeout, risposta diversa da 2xx) 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.