Webhooks

Les webhooks vous notifient en temps réel des événements de vos envois. Dès qu'un événement survient, Conexteo envoie une requête HTTP à l'URL que vous avez déclarée pour le type concerné.

Les trois types

ack_sms : accusés de réception SMS (délivré, échec).

reply : réponses entrantes des destinataires, SMS et RCS (y compris les clics sur les suggestions RCS).

ack_rcs : statuts RCS (délivré, lu, échec, repli SMS). Disponible uniquement en mode signé.

Mode signé ou non signé

Non signé : envoi simple, sans garantie de remise (voir réessais ci-dessous).

Signé (recommandé) : chaque requête porte une signature HMAC à vérifier, et bénéficie des réessais. C'est le mode requis pour ack_rcs.

Vérifier la signature

Chaque webhook signé est envoyé en POST avec trois en-têtes :

En-tête	Contenu
`X-Conexteo-Webhook-Id`	Identifiant unique de l'événement (voir Idempotence).
`X-Conexteo-Timestamp`	Date d'envoi, en secondes depuis le 1er janvier 1970 (epoch).
`X-Conexteo-Signature`	`v1=` suivi de la signature HMAC-SHA256, en hexadécimal minuscule.

La signature se calcule ainsi :

HMAC_SHA256(secret, timestamp + "." + corps_brut)

secret : le secret de signature de votre compte (commence par whsec_). Il vous est remis une seule fois, à l'activation du premier webhook signé, et peut être régénéré via POST /webhooks/secret.

timestamp : la valeur exacte de l'en-tête X-Conexteo-Timestamp.

corps_brut : le corps de la requête tel que reçu, avant tout décodage JSON. Un JSON décodé puis réencodé ne donne pas la même signature.

Pour vérifier un webhook :

Rejetez la requête si le timestamp s'écarte de plus de 5 minutes de l'heure actuelle (protection contre le rejeu).

Calculez la signature attendue avec la formule ci-dessus.

Comparez-la à la valeur reçue après v1=, avec une comparaison à temps constant. Si elles diffèrent, rejetez la requête.

Le préfixe v1= permettra de faire évoluer l'algorithme sans casser les intégrations existantes.

Livraison et réessais

Succès ou échec d'une tentative
Une réponse HTTP 2xx de votre serveur = livré. Tout autre code, un timeout ou une erreur réseau = tentative en échec.

Réessais (webhooks signés uniquement)
Un webhook non signé est envoyé une seule fois : s'il échoue, il n'est pas réessayé. Un webhook signé est réessayé jusqu'à 8 tentatives au total, avec un délai croissant entre chaque :

Après l'échec n°	Prochaine tentative dans
1	30 secondes
2	2 minutes
3	10 minutes
4	30 minutes
5	1 heure
6	4 heures
7	12 heures

Soit une fenêtre de réessai d'environ 18 heures. Passé la 8e tentative sans succès, la livraison est abandonnée (statut failed).

Idempotence
Le header X-Conexteo-Webhook-Id reste identique entre toutes les tentatives d'un même événement. Traitez chaque identifiant une seule fois : c'est votre garantie contre les doublons.

Suivi
Consultez l'état de vos livraisons via GET /webhooks/deliveries (statuts : pending, delivered, failed, cancelled).

Les trois types#

Mode signé ou non signé#

Vérifier la signature#

Livraison et réessais#

Les trois types

Mode signé ou non signé

Vérifier la signature

Livraison et réessais