SendApp Docs
Accedi

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