receptionworksGuida

Integrazioni e webhook

Invia conversazioni, prenotazioni, richieste al team e richieste di assistenza a Zapier, Make o al tuo server; verifica la firma e gli invii.

Le integrazioni inviano gli eventi dell’attività a un altro servizio appena avvengono: una nuova conversazione, una prenotazione, la richiesta di un membro del team, una richiesta di assistenza. Con Zapier o Make puoi, per esempio, aggiungere una riga a un foglio, inviare un messaggio in una chat o creare una scheda nel CRM senza copiare i dati a mano.

Dove trovarle

Apri “Moduli” dal menu superiore, collega il modulo “Integrazioni” (è disattivato per impostazione predefinita) e fai clic su “Apri integrazioni” sulla sua scheda. Si apre “Webhook”, accanto c’è “Registro eventi”. La sezione è accessibile solo a Proprietario e Amministratore: l’indirizzo di un destinatario può contenere un token privato. Finché il modulo è disattivato non viene consegnato nulla e gli eventi avvenuti nel frattempo non vengono rinviati in seguito. I destinatari restano configurati e il registro eventi continua a essere compilato.

Come aggiungere un destinatario

  1. In Zapier crea uno Zap con il trigger “Webhooks by Zapier” e l’evento “Catch Hook” e copia l’indirizzo che ricevi. In Make aggiungi il modulo “Custom webhook” e copia il suo indirizzo.
  2. Nella pagina delle integrazioni compila “Nome” (per esempio il nome dello Zap) e “Indirizzo del destinatario” (l’indirizzo copiato).
  3. In “Eventi da inviare” spunta cosa inviare.
  4. Fai clic su “Aggiungi destinatario”.
  5. Il segreto di firma compare una sola volta. Copialo e conservalo. Zapier e Make non ne hanno bisogno; il tuo server lo usa per verificare la firma. Se lo perdi, creane uno nuovo con “Cambia il segreto”.
  6. Nella scheda del destinatario fai clic su “Invia un test”. Il risultato dice Consegnato o Non consegnato con il motivo.

L’indirizzo deve essere pubblico e iniziare con https. Vengono rifiutati, con il motivo indicato: indirizzi http, indirizzi IP al posto di un dominio, porte personalizzate, indirizzi con nome utente e password, indirizzi interni e indirizzi dei domini di ReceptionWorks. La pagina mostra solo dominio e percorso: la parte dopo il punto interrogativo può contenere il token del tuo destinatario.

Quali eventi vengono inviati

Gli eventi della chat di prova non vengono inviati. Un destinatario riceve solo gli eventi avvenuti dopo la sua aggiunta e finché è attivo: ciò che accade durante una pausa o una disattivazione non viene inviato dopo.

«Nuovo messaggio» e «Conversazione completa» contengono il testo integrale delle conversazioni, compreso ciò che scrivono i clienti. Il testo esce da ReceptionWorks e arriva al destinatario scelto, quindi selezionali solo per destinatari di cui ti fidi. Un nuovo destinatario parte con questi due eventi non selezionati. Vengono inviati solo finché un destinatario li ha selezionati e non compaiono nel registro eventi né nella sua esportazione: la conversazione stessa è nella posta in arrivo. Le chat di prova e i clienti bloccati non vengono inviati.

Cosa riceve il destinatario

Ogni evento è una richiesta POST con un corpo JSON. Esempio per la richiesta di un membro del team fatta da un dipendente IA:

{
  "schema_version": "business-webhook.v1",
  "id": "5b0c5e2e-0000-4000-8000-000000000001",
  "type": "conversation.handoff_requested",
  "occurred_at": "2026-10-07T09:30:00.000Z",
  "business": { "name": "Example Studio" },
  "actor": { "kind": "ai_employee" },
  "channel": "telegram",
  "employee": { "name": "Anna" },
  "conversation": { "url": "https://app.example.com/businesses/studio/inbox?conversation=example" },
  "customer": { "name": "Maria", "email": "maria@example.com", "phone": "+1 555 0100" },
  "booking": null,
  "handoff": { "reason": "ai_request", "reason_text": "The customer wants to discuss a discount" },
  "support_case": null
}

Le sezioni che non riguardano l’evento sono null. L’evento di “Invia un test” ha il tipo webhook.test e tutte le sezioni tranne business sono null. I dati non contengono testo tradotto: i nomi sono come salvati, i codici sono parole inglesi fisse e gli orari sono in UTC.

"message": {
  "id": "6c1d0f52-0000-4000-8000-000000000002",
  "sequence": 12,
  "author": "customer",
  "text": "Hello, can I book for Friday?",
  "created_at": "2026-10-07T09:29:41.000Z",
  "attachments": [{ "kind": "image", "name": "photo.jpg", "media_type": "image/jpeg" }]
}

Messaggi e trascrizioni possono arrivare fuori ordine e ripetersi, quindi non fare affidamento sull’ordine di arrivo. Usa sequence per ripristinare l’ordine dei messaggi di una conversazione e scarta la consegna il cui webhook-id hai già elaborato. La trascrizione ripete messaggi che potresti aver già ricevuto uno a uno: usala per controllare o ricostruire l’intera conversazione.

Come verificare la firma

Ogni richiesta ha tre intestazioni dello standard Standard Webhooks: webhook-id, webhook-timestamp e webhook-signature. Zapier e Make non le verificano. Sul tuo server usa la libreria ufficiale Standard Webhooks per il tuo linguaggio: passale il segreto così com’è mostrato (inizia con whsec_), il corpo originale non modificato e le tre intestazioni. Verifica manuale:

signed_content = webhook-id + "." + webhook-timestamp + "." + raw request body
signature      = "v1," + base64( HMAC-SHA256( key, signed_content ) )
key            = base64-decoded part of the secret after "whsec_"

L’intestazione webhook-signature contiene v1, e la firma. Dopo “Cambia il segreto” contiene due firme separate da uno spazio: accetta la richiesta se ne corrisponde una. Rifiuta le richieste il cui timestamp differisce dal tuo orologio di oltre cinque minuti.

Nuovi tentativi e disattivazione automatica

Il destinatario deve rispondere con un codice 2xx entro 10 secondi. I reindirizzamenti non vengono seguiti: un indirizzo che reindirizza conta come errore. Altrimenti ReceptionWorks riprova: subito, poi dopo 1 minuto, 5 minuti, 30 minuti, 2 ore, 6 ore e 12 ore. Sono 7 tentativi in circa 21 ore. Se falliscono tutti, l’invio è segnato come Non consegnato in “Registro degli invii” e puoi fare clic su “Invia di nuovo”. I nuovi tentativi portano lo stesso webhook-id, quindi il destinatario può scartare i duplicati.

Un destinatario viene disattivato automaticamente se risponde che l’indirizzo non esiste più (codice 410) o se cinque eventi di fila non vengono consegnati. La scheda mostra allora “Disattivato automaticamente” con il motivo e il tuo team riceve una notifica. Correggi l’indirizzo e fai clic su “Attiva”: gli eventi persi nel frattempo non vengono inviati.

Pausa, nuovo segreto, eliminazione

Da sapere

Cosa fare dopo

← Tutti gli articoli