The signing secret is shown once at creation; keep it to verify incoming deliveries.
Webhooks
Receive a signed HTTP notification the moment a verification job finishes, instead of polling the API for a result that is not ready yet.
Register an endpoint and PricklyMails posts to it the moment a job reaches a terminal status, so you can stop polling. A plan allows 1 (Starter), 2 (Pro), 4 (Business), or 10 (Enterprise) endpoints.
Register an endpoint
Create a webhook from the dashboard, or through the /api/webhooks endpoints.
Webhook management authenticates with your dashboard login session, not a pm_ API key.
Warning
The delivery
When a job completes, every active endpoint subscribed to the event receives its own POST with a zero-retention JSON body (only the job UUID and outcome, never the raw email).
Paused and disabled endpoints are skipped.
Each endpoint is signed with its own secret and retried on its own, so one failing endpoint never delays or blocks the others:
Payload
{ "event": "job.completed", "job_uuid": "6f1c...", "status": "completed", "timestamp": 1786464000 }
Verify the signature
Each delivery carries a signature header:
TEXT
X-PricklyMails-Signature: t=1786464000,v1=<hex(hmac_sha256(secret, "<t>.<body>"))>
Recompute hmac_sha256(secret, "<t>.<rawBody>") and compare it to v1 in constant time.
Reject the request if it does not match, or if t is too old for your tolerance.
Retries
Delivery is best-effort, with bounded exponential-backoff retries per endpoint.
After repeated consecutive failures that endpoint, and only that one, is auto-disabled.
An endpoint that already acknowledged an event with a 2xx is never sent the same event for the same job twice.
Note
Webhooks fire for single verifications submitted through POST /api/verify, not for the jobs of a batch: follow a batch with GET /api/batches/{uuid}.
GET /api/verify/{uuid} stays the source of truth if you ever miss a delivery.
Test an endpoint
POST /api/webhooks/{uuid}/test fires one signed sample delivery to the endpoint, so you can confirm your receiver before a real job completes.
The attempt is recorded like a real delivery.
Inspect delivery attempts
GET /api/webhooks/{uuid}/deliveries lists the endpoint's recent delivery attempts (event, job UUID, response status, timestamp), newest first, paginated, and scoped to your account.