Webhook

Notifiche verso i tuoi sistemi — eventi, segreto di firma, header, log di consegna, retry, dead letter e rotazione.

Un webhook invia una richiesta HTTP POST al tuo endpoint ogni volta che si verifica un evento sulla piattaforma. È il modo consigliato per mantenere allineati CRM, gestionale, sistema di ticketing e strumenti di analisi senza interrogare le API.

Prima di iniziare

Endpoint HTTPS pubblico che risponde entro 5 secondi
Capacità di verificare una firma HMAC SHA-256
Ruolo con permesso identity:webhooks:write

Creare un webhook

ConsoleConfigurazioneWebhookNuovo webhook

URL di destinazione

Inserisci un URL HTTPS pubblico, ad esempio https://api.acme.it/hooks/blupantheon. Sono rifiutati HTTP in chiaro, indirizzi IP privati e porte diverse da 443 e 8443.

Ambiente

Seleziona development, staging o production. Un webhook riceve solo gli eventi dell'ambiente scelto.

Eventi sottoscritti

Seleziona i singoli eventi oppure una famiglia con il carattere jolly, ad esempio booking.*. Sottoscrivi solo ciò che consumi davvero.

Header personalizzati

Aggiungi eventuali header richiesti dal tuo gateway, ad esempio X-Tenant: acme.

Salva e copia il segreto

Il segreto di firma viene mostrato una sola volta. Copialo subito nel tuo gestore di segreti.

Esegui un test di consegna

Invia un evento di prova e verifica che il tuo endpoint risponda 200. Poi attiva il webhook.

Segreto di firma

Ogni richiesta è firmata con HMAC SHA-256 sul corpo grezzo, usando il segreto del webhook. La firma viaggia nell'header X-Bp-Signature, il timestamp in X-Bp-Timestamp.

ConsoleConfigurazioneWebhookcrm-acmeSegreto di firma

Segreto di firma del webhook

whsec_xx••••••••••••••

Visibile solo alla creazione. Conservalo in Key Vault o in una variabile d ambiente.

Variabile	Obbligatoria	Default	Descrizione	Esempio
`BP_WEBHOOK_SECRET`	Sì	—	Segreto usato per verificare la firma HMAC delle richieste in arrivo.	`whsec_xxxxxxxxxxxxxxxx`
`BP_WEBHOOK_TOLERANCE_SEC`	No	`300`	Scarto massimo accettato tra il timestamp della richiesta e l ora del server.	`300`
`BP_WEBHOOK_PATH`	No	`/hooks/blupantheon`	Percorso dell endpoint che riceve le notifiche.	`/hooks/blupantheon`

Verifica sempre la firma

Un endpoint webhook non protetto accetta richieste da chiunque ne conosca l'URL. La procedura completa di verifica, con esempi in Node.js, PHP, Python e C#, è in Firma HMAC.

Rotazione del segreto

ConsoleConfigurazioneWebhookcrm-acmeSegreto di firmaRuota

Genera il nuovo segreto

Seleziona Ruota e imposta un periodo di sovrapposizione fino a 48 ore. Durante questo periodo entrambi i segreti sono validi.

Aggiorna il tuo servizio

Configura il nuovo segreto mantenendo temporaneamente la verifica anche con quello precedente.

Verifica i log

Controlla che le consegne firmate con il nuovo segreto risultino 200.

Revoca il precedente

Seleziona Revoca segreto precedente e rimuovi la doppia verifica dal codice.

Ruota il segreto almeno una volta all'anno e immediatamente in caso di sospetta compromissione o di uscita di un collaboratore che vi aveva accesso.

Struttura della richiesta

Richiesta ricevuta dal tuo endpoint

POST /hooks/blupantheon HTTP/1.1
Host: api.acme.it
Content-Type: application/json
User-Agent: BluPantheon-Webhooks/1.0
X-Bp-Event: booking.created
X-Bp-Event-Id: evt_1a2b3c4d5e6f7a8b
X-Bp-Delivery-Id: dlv_9f8e7d6c5b4a3210
X-Bp-Timestamp: 1788508800
X-Bp-Signature: sha256=3f9c1ab2d4e5f60718293a4b5c6d7e8f901a2b3c4d5e6f708192a3b4c5d6e7f8
X-Bp-Attempt: 1
X-Tenant: acme

Corpo della richiesta

{
  "id": "evt_1a2b3c4d5e6f7a8b",
  "type": "booking.created",
  "created_at": "2026-09-04T10:15:32.114Z",
  "environment": "production",
  "tenant": "acme-srl",
  "project_key": "bp_proj_7f3a9c21",
  "data": {
    "booking_id": "bkg_71c9d0a4",
    "session_id": "ses_c41f7d2a9b0e4386",
    "service": { "code": "VIS_CARD", "name": "Visita cardiologica" },
    "starts_at": "2026-09-09T09:00:00+02:00",
    "location": { "code": "MI01", "address": "Via Vittor Pisani 12, Milano" },
    "customer": { "name": "Marco Rossi", "email": "marco.rossi@example.it", "phone": "+39 340 1234567" }
  }
}

Contratto di risposta

Rispondi 2xx entro 5 secondi. Metti in coda l'elaborazione: se il tuo endpoint esegue lavoro sincrono la consegna va in timeout e viene ritentata, generando duplicati.

Catalogo degli eventi

Sessioni e conversazioni

session.created

Quando scatta: un utente apre una nuova conversazione

Contiene canale, lingua, pagina di origine e utente se identificato.

session.ended

Quando scatta: la conversazione si chiude per inattività o per azione dell utente

Include durata, numero di messaggi ed esito.

message.received

Quando scatta: l utente invia un messaggio

Utile per archiviare le trascrizioni nel tuo sistema.

handover.requested

Quando scatta: l assistente o l utente richiede un operatore umano

Contiene il riepilogo della conversazione e la coda di destinazione.

handover.completed

Quando scatta: l operatore chiude la presa in carico

Include l identificativo dell operatore e il tempo di gestione.

session.rated

Quando scatta: l utente lascia una valutazione della conversazione

Contiene punteggio da 1 a 5 ed eventuale commento libero.

Clienti e lead

customer.created

Quando scatta: viene creata una nuova anagrafica dal flusso o dalla Console

Include i dati raccolti e il consenso al trattamento.

customer.updated

Quando scatta: i dati di un cliente esistente vengono modificati

Contiene solo i campi modificati e i valori precedenti.

lead.created

Quando scatta: un flusso qualifica un contatto commerciale

Include servizio di interesse, volume stimato e priorità.

consent.updated

Quando scatta: l utente concede o revoca un consenso

Riporta finalità, base giuridica, data e canale di raccolta.

Prenotazioni

booking.created

Quando scatta: una prenotazione viene confermata

Contiene prestazione, data e ora, sede, professionista e anagrafica.

booking.rescheduled

Quando scatta: una prenotazione viene spostata

Include data precedente e nuova data.

booking.cancelled

Quando scatta: una prenotazione viene annullata

Riporta il motivo e chi ha annullato: utente, operatore o sistema.

booking.reminder_sent

Quando scatta: viene inviato il promemoria dell appuntamento

Utile per riconciliare l invio di SMS e email.

booking.no_show

Quando scatta: l appuntamento viene marcato come mancata presentazione

Include il ritardo rispetto all orario previsto.

Documenti e knowledge base

document.uploaded

Quando scatta: un documento viene caricato nella knowledge base

Contiene nome, dimensione, tipo MIME e sorgente.

document.indexed

Quando scatta: l indicizzazione di un documento si completa con successo

Include numero di chunk generati e durata dell elaborazione.

document.failed

Quando scatta: l elaborazione di un documento fallisce

Riporta codice e messaggio di errore, ad esempio PDF protetto da password.

datastore.reindexed

Quando scatta: una knowledge base completa la reindicizzazione

Contiene il conteggio dei documenti elaborati e di quelli in errore.

Fatturazione e consumi

invoice.issued

Quando scatta: viene emessa una fattura per il tenant

Include importo, periodo di riferimento e link al documento.

invoice.payment_failed

Quando scatta: un pagamento non va a buon fine

Riporta il motivo del rifiuto e la data del prossimo tentativo.

usage.threshold_reached

Quando scatta: il consumo supera una soglia configurata

Contiene metrica, soglia e valore corrente.

subscription.updated

Quando scatta: il piano di abbonamento cambia

Include piano precedente, nuovo piano e data di efficacia.

Sistema

project.published

Quando scatta: una configurazione di progetto viene pubblicata

Contiene versione, autore e nota di rilascio.

tool.failed

Quando scatta: uno strumento restituisce errore dopo tutti i tentativi

Utile per allertare il team che gestisce l endpoint.

webhook.disabled

Quando scatta: un webhook viene disattivato automaticamente per errori ripetuti

Include il numero di consegne fallite consecutive.

security.alert

Quando scatta: viene rilevata un attività anomala sul tenant

Contiene tipo di anomalia, origine e azione applicata.

Il payload completo di ogni evento è documentato in Riferimento webhook.

Header personalizzati

ConsoleConfigurazioneWebhookcrm-acmeHeader personalizzati

Header	Esempio	Uso
`X-Tenant`	`acme`	Instradamento multi-tenant sul tuo gateway
`Authorization`	`Bearer ...`	Autenticazione aggiuntiva sul tuo endpoint
`X-Environment`	`production`	Separazione degli ambienti a valle

Gli header riservati X-Bp-*, Host e Content-Length non possono essere sovrascritti.

Attivazione e disattivazione

Stato	Consegne	Come si raggiunge
Attivo	Sì	Stato normale
In pausa	No, gli eventi vengono scartati	Interruttore manuale
Disabilitato dal sistema	No	100 consegne fallite consecutive o 24 ore di errori

Nessuna coda durante la pausa

Gli eventi generati mentre il webhook è in pausa non vengono conservati. Per recuperarli usa l'endpoint di elenco eventi delle API.

Test di consegna

ConsoleConfigurazioneWebhookcrm-acmeInvia evento di prova

Seleziona il tipo di evento e il profilo di dati (completo o minimale), poi invia. Il pannello mostra richiesta inviata, risposta ricevuta, codice HTTP e latenza. Gli eventi di prova hanno "environment": "test" e non generano effetti sui dati reali.

Log delle consegne

ConsoleConfigurazioneWebhookcrm-acmeConsegne

Colonna	Contenuto
Data e ora	Istante del tentativo, fuso orario del tenant
Evento	Tipo e identificativo dell'evento
Stato	Consegnato, Fallito, In attesa di nuovo tentativo, Dead letter
Codice HTTP	Codice restituito dal tuo endpoint
Latenza	Millisecondi tra invio e risposta
Tentativo	Numero progressivo del tentativo
Azioni	Vedi payload, Copia come cURL, Riconsegna

I log sono conservati 30 giorni ed esportabili in CSV. La funzione Riconsegna rinvia lo stesso payload con un nuovo X-Bp-Delivery-Id.

Retry e backoff esponenziale

Tentativo	Attesa dal precedente	Tempo trascorso
1	—	0
2	30 secondi	30 secondi
3	2 minuti	2,5 minuti
4	10 minuti	12,5 minuti
5	1 ora	1 ora e 13 minuti
6	6 ore	7 ore e 13 minuti
7	24 ore	31 ore e 13 minuti

A ogni attesa viene applicata una variazione casuale fino al 20%. I codici 2xx chiudono la consegna; 4xx diversi da 408 e 429 la interrompono subito perché indicano un errore non ripetibile.

Dead letter

ConsoleConfigurazioneWebhookcrm-acmeDead letter

Dopo il settimo tentativo fallito l'evento entra nella coda dead letter, dove resta 14 giorni. Da lì puoi ispezionare il payload, riconsegnare il singolo evento oppure riconsegnare l'intera coda dopo aver risolto il problema.

Notifica di riempimento

Configura una notifica quando la dead letter supera una soglia: è il segnale più affidabile che il tuo endpoint è fuori servizio.

Buone pratiche

Rispondi subito, elabora dopo. Accoda e restituisci 202 in pochi millisecondi.
Gestisci i duplicati. La consegna è at least once: deduplica su X-Bp-Event-Id.
Non assumere l'ordine. Gli eventi possono arrivare fuori sequenza: usa created_at per ordinarli.
Ignora i campi sconosciuti. Nuovi campi possono essere aggiunti senza preavviso.
Registra tutto. Conserva payload e firma per almeno 30 giorni.
Sottoscrivi il minimo indispensabile. Meno eventi, meno rumore e meno costi.

Passi successivi

Firma HMAC — verifica le richieste in arrivo.
Riferimento webhook — payload completo di ogni evento.
Automazioni e RPA — collega i webhook ai tuoi robot software.

Webhook

In questa pagina