Webhooks
Enregistrez un endpoint et PricklyMails y poste dès qu'un job atteint un statut terminal : vous pouvez arrêter d'interroger.
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_. Le secret de signature est affiché une seule fois à la création ; conservez-le pour vérifier les livraisons entrantes.
La livraison
Quand un job se termine, un endpoint actif abonné à l'événement reçoit un POST avec un corps JSON sans rétention (uniquement l'UUID du job et l'issue, jamais l'email brut) :
{ "event": "job.completed", "job_uuid": "6f1c...", "status": "completed", "timestamp": 1786464000 }
Vérifier la signature
Chaque livraison porte un en-tête de signature :
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é. Après plusieurs échecs consécutifs, l'endpoint est désactivé automatiquement. 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.