POST, une fois par événement, avec une signature HMAC-SHA256.
Les webhooks se créent dans le dashboard, Développeurs › Webhooks, pour un projet et un environnement : l’URL de votre service et les événements voulus. Le secret (whsec_…) n’est montré qu’à la création et à chaque rotation. La création se fait par un membre, jamais par clé API.
Événements
Un envoi groupé à 150 000 destinataires produit 150 000 appels
sms.sent puis autant de sms.delivered : dimensionnez votre point d’entrée en conséquence, ou ne vous abonnez qu’à sms.message.completed.La requête
- Dédoublonnez sur
id: il désigne le fait, et reste le même si la livraison est reprise. - Répondez
2xxen moins de 10 s, puis traitez.
Vérifier la signature
v1 est le HMAC-SHA256, en hexadécimal, de <t>.<corps brut> avec le secret du webhook. Calculez-le sur le corps brut, avant tout JSON.parse, et refusez une signature de plus de cinq minutes.
Reprises et désactivation
Après 50 échecs définitifs d’affilée, le webhook est désactivé ; une livraison réussie remet le compteur à zéro. On le réactive depuis sa fiche, après un test. Le journal des livraisons est gardé 30 jours, et une livraison terminée se relance à la main.
Sécurité
- HTTPS obligatoire.
- Une adresse qui résout vers un réseau privé ou local est refusée, et aucune redirection n’est suivie.
- La rotation du secret est immédiate : l’ancien cesse aussitôt.