Configuri Webhook

Configuri webhook per ricevere notifiche in tempo reale per messaggi, aggiornamenti stato consegna ed eventi campagne.

Si verifica un evento (es. messaggio ricevuto)

Se non riceve 200, ritentiamo con backoff esponenziale

ID univoco dell'evento (usare per la deduplicazione)

Stringa tipo evento (ad es. message.received)

Timestamp ISO 8601 di quando si e verificato l'evento

ID della risorsa che ha generato l'evento

Payload specifico dell'evento (varia per tipo di evento)

Mostra esempio con allegato multimediale

L'array attachments e presente solo quando il messaggio include media. Ogni allegato include un id univoco, content_type, file_size e due URL di download. Tipi supportati: image, video, audio, document, sticker.

url — Endpoint API stabile. Richiede autenticazione (API key o token di sessione). Non scade mai.

signed_url — URL GCS pre-firmato. Nessuna autenticazione richiesta. Scade dopo 24 ore.

Se il download del media dalla piattaforma fallisce, i dati grezzi della piattaforma vengono passati con un marcatore "source": "platform" al posto dei campi arricchiti. I tipi non-file (posizione, contatti, reazioni) non sono interessati.

Ogni evento che include un oggetto contatto contiene anche un array contact_methods[] che elenca tutti gli identificativi del contatto (il principale per primo). I campi phone ed email di primo livello vengono mantenuti per compatibilita con le versioni precedenti.

Le selezioni di risposta rapida e di lista arrivano come message_type "button". La didascalia e in "text" e un oggetto "meta.button" strutturato contiene id e payload, consentendo di instradare la selezione senza analizzare il testo.

Mostra esempio con clic su pulsante (risposta rapida / lista)

Identificatore stabile del pulsante come definito al momento dell'invio del messaggio.

Payload restituito dal canale (corrisponde all'id per le risposte rapide).

Didascalia leggibile che l'utente ha visto e toccato.

I messaggi in uscita che includono allegati file contengono lo stesso schema arricchito degli allegati (id, url, signed_url, content_type, file_size) dei messaggi in entrata.

Il campo error si trova a livello data (non dentro message.meta). Sono inclusi anche gli oggetti conversation e contact completi.

Gli eventi di aggiornamento dello stato (delivered, read) utilizzano un oggetto conversation piu semplice senza bot_session_id o campi timestamp last_*_at. L'oggetto contact_method non e incluso.

Gli oggetti conversation delle email includono campi aggiuntivi: email_integration_id e email_thread_id per il contesto di threading.

L'evento reopened include meno campi della conversazione rispetto ad altri eventi (nessun bot_session_id, timestamp last_*_at o subject).

contact.updated e contact.deleted utilizzano la stessa struttura. Il campo type dell'evento li distingue.

Ottenga il corpo richiesta grezzo (prima del parsing JSON)

Calcoli HMAC-SHA256 usando il suo segreto webhook

Confronti con l'header X-SendSeven-Signature

Usi confronto timing-safe per prevenire attacchi timing

Il suo URL sia accessibile pubblicamente (non localhost)

Il suo certificato SSL sia valido (non autofirmato)

Non ci sia firewall che blocca gli IP SendSeven

Usa JSON parsato invece del corpo grezzo

Segreto webhook errato (lo copi di nuovo dalle impostazioni)

Middleware che modifica il corpo richiesta

Memorizzi l'ID evento e controlli duplicati prima dell'elaborazione

Risponda con 200 il più rapidamente possibile (elabori async)

I Webhook sono callback HTTP che SendSeven utilizza per inviare eventi in tempo reale alla tua applicazione. Invece di interrogare la REST API, il tuo endpoint riceve notifiche istantanee quando accade qualcosa di importante: un messaggio in arrivo, una conversazione chiusa, un contatto creato o un cambio di stato della consegna. Ogni richiesta webhook viene firmata con HMAC per la sicurezza e ritentata automaticamente in caso di errore con backoff esponenziale, garantendo che nessun evento vada perso.

Un account SendSeven con almeno un canale collegato

Un endpoint HTTPS pubblico in grado di ricevere richieste HTTP POST

Un certificato SSL valido (Let's Encrypt funziona perfettamente)

Conoscenza base delle REST API e del formato JSON

Pagina Webhook nella dashboard SendSeven con il pulsante Add Endpoint evidenziato

Finestra di dialogo Add Endpoint con campo URL HTTPS e sottoscrizioni eventi in SendSeven

Popup Webhook creato con successo che mostra la chiave segreta e il pulsante Copia

Pagina di dettaglio del webhook che mostra URL dell'endpoint, eventi sottoscritti, storico consegne e stato di salute in SendSeven

Automaticamente alla creazione di un webhook tramite la dashboard

Automaticamente alla creazione di un webhook tramite API (POST /api/v1/webhook-endpoints)

Automaticamente quando l'URL del webhook viene aggiornato

Su richiesta tramite l'endpoint di verifica (POST /api/v1/webhook-endpoints/{id}/verify)

1. Crea un endpoint webhook
2. Registra il webhook in SendSeven
3. Seleziona i tipi di eventi da ricevere
4. Gestisci la verifica del webhook
5. Verifica la firma del webhook
6. Gestisci gli eventi in arrivo
7. Testa con eventi di esempio