Le secret de signature est affiché une seule fois à la création ; conservez-le pour vérifier les livraisons entrantes.
Webhooks
Recevez une notification HTTP signée dès qu'un job de vérification se termine, plutôt que d'interroger l'API pour un résultat pas encore prêt.
Enregistrez un endpoint et PricklyMails y poste dès qu'un job atteint un statut terminal : vous pouvez arrêter d'interroger. Une offre autorise 1 (Starter), 2 (Pro), 4 (Business) ou 10 (Enterprise) endpoints.
Enregistrer un endpoint
Créez un webhook depuis le dashboard, ou via les endpoints /api/webhooks.
La gestion des webhooks s'authentifie avec votre session de connexion au dashboard, pas avec une clé API pm_.
Attention
La livraison
Quand un job se termine, chaque endpoint actif abonné à l'événement reçoit son propre POST avec un corps JSON sans rétention (uniquement l'UUID du job et l'issue, jamais l'email brut).
Les endpoints en pause ou désactivés sont ignorés.
Chaque endpoint est signé avec son propre secret et relancé indépendamment : un endpoint en échec ne retarde ni ne bloque jamais les autres :
Corps
{ "event": "job.completed", "job_uuid": "6f1c...", "status": "completed", "timestamp": 1786464000 }
Vérifier la signature
Chaque livraison porte un en-tête de signature :
TEXT
X-PricklyMails-Signature: t=1786464000,v1=<hex(hmac_sha256(secret, "<t>.<body>"))>
Recalculez hmac_sha256(secret, "<t>.<corpsBrut>") et comparez-le à v1 en temps constant.
Rejetez la requête si ça ne correspond pas, ou si t est trop ancien pour votre tolérance.
Retries
La livraison est best-effort, avec des retries à backoff exponentiel borné par endpoint.
Après plusieurs échecs consécutifs, cet endpoint, et lui seul, est désactivé automatiquement.
Un endpoint qui a déjà acquitté un événement par un 2xx ne reçoit jamais deux fois le même événement pour le même job.
À noter
Les webhooks se déclenchent pour les vérifications unitaires envoyées via POST /api/verify, pas pour les jobs d'un batch : suivez un batch avec GET /api/batches/{uuid}.
GET /api/verify/{uuid} reste la source de vérité si vous manquez une livraison.
Tester un endpoint
POST /api/webhooks/{uuid}/test envoie une livraison d'exemple signée à l'endpoint, pour confirmer votre récepteur avant qu'un vrai job ne se termine.
La tentative est enregistrée comme une vraie livraison.
Inspecter les tentatives de livraison
GET /api/webhooks/{uuid}/deliveries liste les tentatives de livraison récentes de l'endpoint (événement, UUID du job, statut de réponse, horodatage), les plus récentes d'abord, paginées et limitées à votre compte.