Skip to content

Webhooks

Register an endpoint and PricklyMails posts to it the moment a job reaches a terminal status, so you can stop polling.

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. The signing secret is shown once at creation; keep it to verify incoming deliveries.

The delivery

When a job completes, an active endpoint subscribed to the event receives a POST with a zero-retention JSON body (only the job UUID and outcome, never the raw email):

{ "event": "job.completed", "job_uuid": "6f1c...", "status": "completed", "timestamp": 1786464000 }

Verify the signature

Each delivery carries a signature header:

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. After repeated consecutive failures the endpoint is auto-disabled. 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.