Webhooks

Webhooks let your application react to email events in real time.

Supported events

Event	Fired when
inbound_email	A new inbound message arrives.
delivery_status	Outbound message delivery status changes.
bounce	A delivery attempt bounces.
complaint	A recipient marks the message as spam.
domain_verified	A domain's DNS records are fully verified.
mailbox_created	A new mailbox is created.
migration_complete	A mail migration finishes.
rate_limit_warning	Your account is approaching a rate limit.
all	Subscribe to every event.

Create a webhook

curl -X POST https://api.purpletoadmail.com/api/v1/webhooks \
  -H "Authorization: Bearer pt_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/purpletoad",
    "events": ["delivery_status", "bounce", "inbound_email"]
  }'

The API generates a secret for you and returns it once in the response. Store it securely — it is used to verify webhook signatures.

Signature verification

Every webhook request includes an X-PurpleToad-Signature header in the format sha256=<digest>. Compute an HMAC-SHA256 of the raw body using your webhook secret and compare the prefixed value.

import hmac, hashlib

digest = hmac.new(secret.encode(), body.encode(), hashlib.sha256).hexdigest()
signature_header = request.headers['X-PurpleToad-Signature']
expected = f"sha256={digest}"
assert hmac.compare_digest(expected, signature_header)

Webhook deliveries also include X-PurpleToad-Event, X-Event-ID, and X-PurpleToad-Timestamp headers.