Webhooks
Les webhooks poussent les événements vers votre backend à l'instant où ils se produisent — un message a été délivré, un lien a été cliqué, un contact s'est désinscrit. Chaque payload est signé pour que vous puissiez lui faire confiance, et les livraisons échouées sont réessayées avec backoff pour qu'une brève panne ne perde jamais un événement.
Ce dont vous aurez besoin
- Un endpoint HTTPS public pour recevoir les POST
- Une clé API ou un accès administrateur pour enregistrer le webhook
Enregistrer un endpoint
- 1
Ouvrez Paramètres → Webhooks
Ou appelez POST /v1/workspaces/{workspace_id}/webhooks. Indiquez votre URL HTTPS et choisissez les événements souhaités.
- 2
Conservez le secret de signature
Chaque webhook possède un secret, affiché à la création. Vous l'utiliserez pour vérifier chaque requête entrante.
- 3
Ajoutez des en-têtes personnalisés (facultatif)
Attachez des en-têtes (par exemple un token d'authentification) que Climails enverra à chaque livraison vers votre endpoint.
Les événements auxquels vous pouvez vous abonner
- Email — email.delivered, email.bounce, email.complaint, email.unsubscribe, email.opened, email.clicked.
- SMS — sms.delivered, sms.failed.
- Contacts — contact.subscribed, contact.unsubscribed, contact.changed.
- Campagnes — campaign.finished.
Vérifier la signature
Chaque requête porte X-Senderbox-Timestamp et X-Senderbox-Sig. Recalculez le HMAC et comparez — rejetez tout ce qui ne correspond pas, et rejetez les horodatages anciens pour bloquer les rejeux.
// signature = HMAC_SHA256(secret, timestamp + "." + rawBody)
import crypto from "node:crypto";
function verify(rawBody, headers, secret) {
const ts = headers["x-senderbox-timestamp"];
const sig = headers["x-senderbox-sig"]; // "sha256=<hex>"
const expected = "sha256=" + crypto
.createHmac("sha256", secret)
.update(ts + "." + rawBody)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}Nouvelles tentatives et échecs
Renvoyez un 2xx rapidement pour accuser réception. Si votre endpoint renvoie une erreur ou expire, Climails réessaie avec un backoff croissant : 30s, 2m, 10m, 1h, 6h, 24h.
- Après 6 tentatives échouées, la livraison est abandonnée.
- Un 4xx (sauf 408 et 429) est considéré comme définitif et n'est pas réessayé — corrigez l'endpoint et la livraison reprendra au prochain événement.
- Les endpoints sont protégés contre le SSRF : les adresses internes/privées sont refusées.
Questions fréquentes
Comment vérifier qu'un webhook provient bien de Climails ?
Recalculez HMAC-SHA256 sur timestamp + "." + corps brut avec le secret du webhook et comparez à X-Senderbox-Sig. Utilisez une comparaison à temps constant.
Que se passe-t-il si mon serveur est hors ligne ?
Les livraisons sont réessayées avec backoff (30s → 24h) sur jusqu'à 6 tentatives, si bien qu'une courte panne ne perd pas d'événements.
Pourquoi mon webhook a-t-il cessé de réessayer immédiatement ?
Une réponse 4xx (autre que 408/429) est considérée comme une erreur permanente. Corrigez le handler ; les nouveaux événements reprennent leur livraison.
Commencez à envoyer en quelques minutes
Créez un compte gratuit, connectez votre domaine et touchez votre audience sur tous les canaux — sans carte bancaire.
Offre gratuite à vie · Sans carte bancaire · Prêt en quelques minutes