Configurer les Webhooks

Configurez les webhooks pour recevoir des notifications en temps réel sur les messages, les mises à jour de statut de livraison et les événements de campagne.

conversation.created — Nouvelle conversation

conversation.closed — Conversation fermée

Un événement se produit (par ex., message reçu)

SendSeven envoie une requête HTTP POST à votre URL

Si pas de 200, nous réessayons avec backoff exponentiel

Événements : Sélectionnez les événements à recevoir

ID unique de l'événement (utiliser pour la déduplication)

ID de la ressource ayant déclenche l'événement

Payload spécifique à l'événement (varie selon le type)

Afficher un exemple avec pièce jointe media

Le tableau attachments n'est présent que lorsque le message inclut un media. Chaque pièce jointe comprend un id unique, content_type, file_size et deux URLs de téléchargement. Types pris en charge : image, video, audio, document, sticker.

url — Endpoint API stable. Nécessite une authentification (clé API ou token de session). N'expire jamais.

signed_url — URL GCS pré-signée. Aucune authentification requise. Expire après 24 heures.

Si le téléchargement media de la plateforme échoue, les données brutes de la plateforme sont transmises avec un marqueur "source": "platform" au lieu des champs enrichis. Les types non-fichier (localisation, contacts, réactions) ne sont pas affectés.

Chaque événement incluant un objet contact contient également un tableau contact_methods[] listant tous les identifiants du contact (le principal en premier). Les champs phone et email de premier niveau sont conservés pour la compatibilité ascendante.

Les sélections de réponse rapide et de liste arrivent avec message_type "button". La légende est dans "text" et un objet "meta.button" structure contient l'id et le payload, ce qui permet de router la sélection sans analyser le texte.

Afficher un exemple avec clic sur bouton (réponse rapide / liste)

Identifiant stable du bouton tel que défini lors de l'envoi du message.

Payload retourne par le canal (correspond à l'id pour les réponses rapides).

Légende lisible que l'utilisateur a vue et touchée.

Les messages sortants incluant des pièces jointes contiennent le même schema enrichi (id, url, signed_url, content_type, file_size) que les messages entrants.

Le champ error est au niveau data (pas dans message.meta). Les objets conversation et contact complets sont également inclus.

Les événements de mise à jour de statut (delivered, read) utilisent un objet conversation simplifié sans bot_session_id ni champs d'horodatage last_*_at. L'objet contact_method n'est pas inclus.

Les objets conversation email incluent des champs supplémentaires : email_integration_id et email_thread_id pour le contexte de fil de discussion.

L'événement reopened inclut moins de champs de conversation que les autres événements de conversation (pas de bot_session_id, d'horodatages last_*_at ou de subject).

contact.updated et contact.deleted utilisent la même structure. Le champ type de l'événement permet de les distinguer.

Obtenez le corps brut de la requête (avant parsing JSON)

Calculez HMAC-SHA256 en utilisant votre secret webhook

Comparez avec l'en-tête X-SendSeven-Signature

Utilisez une comparaison sécurisée contre les attaques temporelles

Votre URL est accessible publiquement (pas localhost)

Votre certificat SSL est valide (pas auto-signé)

Votre serveur autorise les requêtes POST

Aucun pare-feu ne bloque les IP de SendSeven

Utilisation de JSON analysé au lieu du corps brut

Mauvais secret webhook (copiez-le à nouveau depuis les paramètres)

Middleware modifiant le corps de la requête

Stockez l'ID de l'événement et vérifiez les doublons avant traitement

Rendez vos gestionnaires d'événements idempotents

Répondez avec 200 aussi rapidement que possible (traitement async)

Les Webhooks sont des callbacks HTTP que SendSeven utilise pour envoyer des événements en temps réel à votre application. Au lieu d'interroger l'API REST, votre endpoint reçoit des notifications instantanées lorsqu'un événement important se produit — un message arrive, une conversation se termine, un contact est créé ou un statut de livraison change. Chaque requête webhook est signée par HMAC pour la sécurité et automatiquement retentée en cas d'échec avec un backoff exponentiel, garantissant qu'aucun événement n'est perdu.

Un compte SendSeven avec au moins un canal connecté

Un endpoint HTTPS public capable de recevoir des requêtes HTTP POST

Un certificat SSL valide (Let's Encrypt fonctionne très bien)

Une compréhension de base des API REST et du JSON

Page Webhooks du tableau de bord SendSeven avec le bouton Ajouter un endpoint mis en évidence

Dialogue Ajouter un endpoint avec le champ URL HTTPS et les abonnements aux événements dans SendSeven

En-tête Authorization (optionnel) : En-tête d'authentification personnalisé envoyé à chaque livraison

Via l'API, vous pouvez également configurer : retry_strategy (exponential/linear/none), max_retries (par défaut 8, max 15) et timeout_seconds (par défaut 30, plage 5–60)

Popup Webhook créé avec succès affichant la clé secrète avec un bouton Copier

Page de détail du webhook affichant l'URL de l'endpoint, les événements souscrits, l'historique de livraison et l'état de santé dans SendSeven

Automatiquement lors de la création d'un webhook via le tableau de bord

Automatiquement lors de la création d'un webhook via l'API (POST /api/v1/webhook-endpoints)

Automatiquement lorsque l'URL du webhook est modifiée

À la demande via l'endpoint de vérification (POST /api/v1/webhook-endpoints/{id}/verify)

1. Créer un point de terminaison webhook
2. Enregistrer le webhook dans SendSeven
3. Sélectionner les types d'événements à recevoir
4. Gérer la vérification du webhook
5. Vérifier la signature du webhook
6. Traiter les événements entrants
7. Tester avec des événements exemples