Webhook in uscita: come funzionano
SendApp chiama il tuo server quando succede qualcosa nel tuo account: arriva o parte un messaggio, WhatsApp aggiorna lo stato di un messaggio, una campagna inizia o finisce, un modello WhatsApp viene approvato o rifiutato, viene preso un appuntamento. Si configura da Impostazioni → Webhook: fino a 10 indirizzi, ognuno con il suo account AI e i suoi eventi.
Ogni chiamata è una richiesta POST con un corpo JSON e gli header
X-SendApp-Event, X-SendApp-Delivery (l'id unico della consegna), X-SendApp-Attempt e X-SendApp-Signature.Verifica la firma:
X-SendApp-Signature vale t=<timestamp>,v1=<HMAC-SHA256 di "timestamp.corpo">, calcolato con la chiave segreta del webhook (Impostazioni → Webhook → Mostra la chiave di firma). Rifiuta le richieste con un timestamp più vecchio di 5 minuti.Rispondi con un codice 2xx entro 10 secondi: altrimenti riproviamo dopo 1, 5 e 30 minuti. Un codice 4xx (tranne 408 e 429) non viene ritentato. Dopo 20 consegne fallite di fila il webhook si spegne: lo riaccendi da Impostazioni → Webhook.
Ogni consegna ha un
delivery_id unico, uguale in tutti i tentativi: usalo per ignorare i doppioni. L'ordine di arrivo non è garantito: per mettere in fila gli eventi usa occurred_at (e timestamp per gli stati).Il corpo contiene sempre
event, occurred_at, account_ref, training_token (l'account AI) e delivery_id. account_ref identifica il tuo account e non è una chiave: il corpo non contiene mai la tua chiave API. Foto, audio, video e documenti arrivano come link, mai come file.Da Impostazioni → Webhook puoi mandare una prova di ogni evento: arriva con
"test": true. Il registro mostra ogni consegna con il corpo inviato e la risposta del tuo server.Parametri
8 · 0 obbligatori
message.received
opzionale
Un cliente ti scrive, su qualsiasi canale.
message.sent
opzionale
Parte un messaggio: AI, operatore, campagna, automazione, API.
message.status
opzionale
Un messaggio WhatsApp è stato consegnato, letto o non consegnato (con il codice di errore di Meta).
campaign.started
opzionale
Una campagna inizia a inviare.
campaign.completed
opzionale
Una campagna ha finito, con i suoi numeri.
campaign.failed
opzionale
Una campagna si è fermata per un errore.
template.status_changed
opzionale
Un modello WhatsApp è stato approvato, rifiutato, messo in pausa o disattivato, con il motivo.
booking.* / voice.*
opzionale
Gli appuntamenti dell'Agenda e le chiamate della Voice AI: stessi indirizzi, stessa firma.
Serve aiuto con l'integrazione? info@sendapp.live