Webhook: inviare le prenotazioni ad Airtable

A che cosa servono i webhook

Un webhook invia automaticamente all'indirizzo web da Lei scelto i dati di ogni prenotazione, di ogni spostamento e di ogni annullamento, non appena avvengono.

Lo strumento che li riceve può inserirli in una tabella, avvisare qualcuno o avviare altre azioni. Calenoo si limita all'invio: il resto si imposta in quello strumento.

L'impostazione si fa una sola volta, nelle Sue Impostazioni, e vale per tutte le Sue pagine di prenotazione. Può registrare al massimo 3 indirizzi.

Le basta un account Calenoo: la voce «Webhooks» si trova nelle Sue Impostazioni, come le pagine di prenotazione.

I webhook si abbinano alla convalida delle richieste e alle sessioni di gruppo, altre due funzioni avanzate delle pagine di prenotazione. Vedi la guida alle funzioni avanzate.

Passo dopo passo: Airtable

Questi passaggi seguono la documentazione di Airtable sul trigger «When webhook received» (fonte, letta il 2 novembre 2026). Se la schermata di Airtable è diversa da quella descritta qui, fa fede la sua pagina di aiuto.

1. Nella Sua base Airtable, apra «Automations» e crei un'automazione.
2. Aggiunga un trigger e scelga «When webhook received». Airtable mostra un indirizzo web univoco: lo copi.
3. In Calenoo, apra Impostazioni › Webhooks, incolli l'indirizzo in «Indirizzo di ricezione» e clicchi su «Aggiungi».
4. Lasci deselezionata la casella «Firmare le trasmissioni»: Airtable non sa verificare una firma.
5. Clicchi su «Invia un test». Calenoo invia un esempio di prenotazione completo, senza campi vuoti, e mostra «Test ricevuto» quando Airtable accetta la trasmissione.
6. In Airtable, avvii il test del trigger (pulsante «Run test»). Airtable usa la trasmissione di test come esempio per i passaggi successivi.
7. Aggiunga le azioni che useranno questi dati e vi associ i campi ricevuti. Per ritrovare un appuntamento spostato o annullato, usi booking.id come identificativo.
8. Provi ogni passaggio, poi attivi l'automazione (da OFF a ON). Da quel momento, ogni prenotazione delle Sue pagine parte verso Airtable.

Che cosa dice Airtable su questo trigger

Letto sulla pagina di aiuto di Airtable il 2 novembre 2026. Questi limiti sono quelli di Airtable e possono cambiare.

• Sono accettate solo richieste POST, con un'intestazione Content-Type impostata su application/json per il JSON. È ciò che invia Calenoo.
• Una trasmissione non deve superare 100 kb, e il trigger accetta al massimo cinque richieste al secondo.
• Ogni trasmissione che avvia un'automazione conta nei limiti di esecuzione del Suo piano Airtable. Il trigger è disponibile in tutti i tipi di piano, con limiti diversi.
• Airtable non supporta la verifica della firma: tenga disattivata la firma di Calenoo per Airtable.
• Chiunque conosca l'indirizzo del trigger può avviare la Sua automazione. Non lo condivida.

Gli eventi inviati

Calenoo invia tutti gli eventi della tabella, senza possibilità di selezione: il Suo strumento legge il campo event e tiene quelli che gli servono.

Ogni trasmissione riguarda un solo appuntamento. Per una pagina di gruppo (più posti per slot), ogni partecipante ha una trasmissione distinta, con il proprio booking.id e il booking.session_id della sua sessione, uguale per tutti i partecipanti.

Il formato dei dati

Ogni trasmissione è una richiesta POST il cui corpo è JSON (versione 1). Ecco un esempio. Il pulsante «Invia un test» invia lo stesso formato, con test su true e tutti i campi compilati.

{
  "version": 1,
  "event": "booking.created",
  "event_id": "5d0c6b0e-6b0a-4a52-9d5c-2f1d3c9a7e11",
  "occurred_at": "2026-11-02T18:00:00Z",
  "test": false,
  "booking": {
    "id": "b3f1c2a4-8d7e-4c6b-9a10-5e2f4d8c1a77",
    "status": "confirmed",
    "previous_status": null,
    "start": "2026-11-07T09:00:00Z",
    "end": "2026-11-07T10:00:00Z",
    "start_local": "2026-11-07T10:00:00+01:00",
    "end_local": "2026-11-07T11:00:00+01:00",
    "timezone": "Europe/Zurich",
    "duration_minutes": 60,
    "previous_start": null,
    "location": "Bern",
    "meeting_url": null,
    "language": "de",
    "request_expires_at": null,
    "seats": null,
    "session_id": null,
    "invitee": {
      "name": "Jeanne Fit",
      "email": "jeanne@example.ch",
      "note": "Looking forward to it"
    }
  },
  "page": {
    "id": "9a4e7d52-3c1b-4f08-8e66-0b7d2a5c9f33",
    "slug": "personal-training",
    "title": "Personal Training"
  }
}

I campi principali

• event: l'evento (vedi la tabella qui sopra). event_id: un identificativo comune a tutti gli indirizzi che ricevono lo stesso evento. occurred_at: l'ora dell'evento, in tempo universale (UTC).
• booking.id: l'identificativo dell'appuntamento. È la chiave da usare per ritrovarlo.
• booking.status e booking.previous_status: lo stato dell'appuntamento e il suo stato precedente (null se non ce n'è uno).
• booking.start e booking.end: inizio e fine in tempo universale (UTC). booking.start_local e booking.end_local: gli stessi orari, con l'ora e lo scarto del fuso orario della pagina (booking.timezone). booking.duration_minutes: la durata in minuti.
• booking.previous_start: l'inizio precedente, in caso di spostamento; altrimenti null.
• booking.location, booking.language e booking.meeting_url: il luogo della pagina, la lingua della prenotazione e il link della videoconferenza (null se non ce n'è uno). Una richiesta in attesa non ha ancora un link: arriva con booking.accepted.
• booking.request_expires_at: la scadenza di una richiesta da convalidare (al massimo 48 ore, mai dopo l'inizio dell'appuntamento), altrimenti null. Resta compilata dopo la decisione.
• booking.seats: il numero di posti per slot di una pagina di gruppo, null per un appuntamento individuale.
• booking.session_id: l'identificativo della sessione di una pagina di gruppo, uguale per tutti i partecipanti, null per un appuntamento individuale. Resta compilato dopo un annullamento; uno spostamento indica quello della nuova sessione.
• booking.invitee: il nome, l'indirizzo email e il messaggio (note, null se non ce n'è uno) dell'ospite.
• page: l'identificativo, l'indirizzo breve (slug) e il titolo della pagina di prenotazione.

Le intestazioni

• Content-Type: application/json
• User-Agent: Calenoo-Webhook/1
• Calenoo-Event: l'evento, per esempio booking.created.
• Calenoo-Delivery: l'identificativo della trasmissione. Resta identico a ogni nuovo tentativo: lo usi per ignorare un duplicato.
• Calenoo-Signature: presente solo se la firma è attivata (vedi sotto).

La struttura della versione 1 non cambia: qualsiasi modifica passerebbe da una versione 2.

Verificare la firma

Questo passaggio è facoltativo. Se seleziona «Firmare le trasmissioni», Calenoo aggiunge l'intestazione Calenoo-Signature a ogni trasmissione: il Suo strumento può così verificare che la trasmissione provenga davvero da Calenoo e non sia stata modificata.

L'intestazione ha la forma t=<secondi>,v1=<firma>. t è l'ora di invio in secondi (ora Unix). v1 è un HMAC-SHA256 in esadecimale, calcolato con il Suo segreto sul testo t.corpo: t, un punto, poi il corpo della richiesta esattamente come è stato ricevuto.

Il segreto inizia con whsec_: lo usi per intero, prefisso compreso. Calenoo lo mostra una sola volta, alla creazione: lo copi subito. Se lo perde, ne crei uno nuovo con «Nuovo segreto».

Ecco un esempio in JavaScript (Node.js). Calcoli sempre la firma sul testo grezzo ricevuto, prima di qualsiasi JSON.parse. Rifiuti anche una trasmissione il cui t è troppo vecchio: qui, più di 5 minuti.

import crypto from "node:crypto";

function isValidSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const received = Buffer.from(parts.v1 ?? "", "hex");
  const computed = Buffer.from(expected, "hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && received.length === computed.length && crypto.timingSafeEqual(received, computed);
}

Node.js scrive i nomi delle intestazioni in minuscolo: l'intestazione si legge con req.headers['calenoo-signature'].

In caso di guasto

Una trasmissione riesce quando il Suo strumento risponde con un codice 2xx entro 10 secondi. Calenoo non legge mai il contenuto della risposta e non segue nessun reindirizzamento: una risposta 3xx conta come un fallimento.

• Risposta 408, 425, 429 o 5xx, tempo scaduto o interruzione di rete: Calenoo riprova, al massimo 8 tentativi (il primo compreso), dopo 1, 2, 5, 15 e 30 minuti, poi 1 ora e 2 ore. Se la risposta contiene un'intestazione Retry-After (in secondi) più lunga di questa attesa, Calenoo la rispetta, fino a un massimo di 6 ore.
• Qualsiasi altra risposta 4xx (404 o 401, per esempio): fallimento definitivo, nessun nuovo tentativo.
• Le trasmissioni verso uno stesso indirizzo partono in ordine: una trasmissione in attesa di un nuovo tentativo trattiene quelle successive.
• Dopo 5 trasmissioni consecutive in fallimento definitivo, Calenoo disattiva l'indirizzo e Le invia un'email. Una trasmissione riuscita azzera il contatore.
• Le trasmissioni perse non vengono reinviate quando riattiva l'indirizzo. Risolto il problema, clicchi su «Riattiva» in Impostazioni › Webhooks.

Una stessa trasmissione può arrivare due volte, per esempio se il Suo strumento l'ha ricevuta ma la sua risposta si è persa. Poiché Calenoo-Delivery è identico a ogni tentativo, il Suo strumento può ignorare un duplicato.

Il registro «Ultime trasmissioni» in Impostazioni › Webhooks mostra l'evento, il codice di risposta e lo stato di ogni trasmissione. Viene conservato 30 giorni, senza il contenuto delle trasmissioni.

Sicurezza e dati personali

• Calenoo invia solo in https, sulla porta 443. Un indirizzo con nome utente o password, o su un'altra porta, viene rifiutato.
• Gli indirizzi privati o locali (rete interna, localhost…) vengono rifiutati al salvataggio, poi ricontrollati prima di ogni trasmissione.
• Mai nelle trasmissioni: i link e i token per gestire l'appuntamento, l'impronta IP, il Suo indirizzo email e i riferimenti della Sua agenda.
• Il contenuto di ogni trasmissione viene cancellato non appena la trasmissione è terminata.
• Il controllo resta Suo: può mettere in pausa un indirizzo, firmarlo, cambiarne il segreto o eliminarlo in qualsiasi momento.

Ogni trasmissione contiene dati personali: il nome, l'indirizzo email e il messaggio dell'ospite, con l'orario dell'appuntamento. Vanno allo strumento da Lei scelto, che li tratta sotto la propria responsabilità e secondo le proprie condizioni. Vedi l'informativa sulla privacy.

Domande frequenti

Serve un piano Airtable a pagamento?

Airtable indica che il trigger «When webhook received» è disponibile in tutti i tipi di piano, con limiti diversi. Ogni trasmissione che avvia un'automazione conta nei limiti di esecuzione del Suo piano: li verifichi nel Suo account Airtable (fonte).

Il mio strumento è in panne: si perdono delle prenotazioni?

No, le prenotazioni restano in Calenoo. Riguarda solo l'invio verso il Suo strumento: Calenoo riprova fino a 8 volte, con attese da 1 minuto a 2 ore. Dopo 5 trasmissioni consecutive in fallimento definitivo, l'indirizzo viene disattivato e le trasmissioni perse non vengono reinviate.

Posso ricevere solo alcuni eventi?

No: Calenoo invia tutti gli eventi. Il Suo strumento legge il campo event (o l'intestazione Calenoo-Event) e tiene quelli che vuole trattare.

Come evito i duplicati nella mia tabella?

Usi booking.id come chiave: uno spostamento o un annullamento riguarda lo stesso appuntamento e può quindi aggiornare la stessa riga. L'intestazione Calenoo-Delivery identifica ogni trasmissione e resta identica a ogni nuovo tentativo.

Posso inviare a un server della mia rete interna o su un'altra porta?

No. Calenoo invia solo in HTTPS, sulla porta 443, verso un indirizzo pubblico.