Webhooks

Subscribe to real-time email event notifications. Posthawk sends signed HTTP POST requests to your endpoint when email events occur.

Webhook endpoints receive POST requests with a JSON payload for each email event. Each delivery is signed with HMAC SHA-256 so you can verify authenticity.

Supported events: send, delivery, bounce, complaint, reject, delivery_delay, open, click

Signature verification: Each request includes an X-Posthawk-Signature header with the format sha256={hex_digest}. Compute HMAC SHA-256 of the raw request body using your webhook secret and compare.

Headers sent with each webhook delivery:
• Content-Type: application/json
• X-Posthawk-Signature: sha256={hmac_hex}
• X-Posthawk-Event: {event_type}
• User-Agent: Posthawk-Webhook/1.0

Webhook secrets are auto-generated when you create an endpoint and returned in the response. Store the secret securely — it is used to verify that requests are genuinely from Posthawk.

GET/v1/webhooksAPI Key

List all webhook endpoints for the authenticated workspace.

Response

json

[
  {
    "id": "uuid",
    "url": "https://yourapp.com/api/webhooks/posthawk",
    "secret": "whsec_...",
    "events": ["delivery", "bounce", "complaint"],
    "enabled": true,
    "description": "Production webhook",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z"
  }
]

POST/v1/webhooksAPI Key

Create a new webhook endpoint. A signing secret is auto-generated and returned.

Parameter	Type	In	Description
`url`required	`string`	body	The URL to receive webhook POST requests
`events`required	`string[]`	body	Array of event types to subscribe to: send, delivery, bounce, complaint, reject, delivery_delay, open, click
`description`	`string`	body	Human-readable label for this endpoint

Request

bash

curl -X POST https://api.posthawk.dev/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "url": "https://yourapp.com/api/webhooks/posthawk",
    "events": ["delivery", "bounce", "complaint"],
    "description": "Production webhook"
  }'

Response

json

{
  "id": "uuid",
  "url": "https://yourapp.com/api/webhooks/posthawk",
  "secret": "whsec_...",
  "events": ["delivery", "bounce", "complaint"],
  "enabled": true,
  "description": "Production webhook",
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-01-15T10:00:00Z"
}

PATCH/v1/webhooks/:idAPI Key

Update a webhook endpoint — change the URL, subscribed events, enabled state, or description.

Parameter	Type	In	Description
`id`required	`string`	path	Webhook endpoint UUID
`url`	`string`	body	New webhook URL
`events`	`string[]`	body	New event subscriptions
`enabled`	`boolean`	body	Enable or disable the endpoint
`description`	`string`	body	Updated description

Request

bash

curl -X PATCH https://api.posthawk.dev/v1/webhooks/uuid \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "events": ["delivery", "bounce", "complaint", "open", "click"],
    "description": "Updated production webhook"
  }'

Response

json

{
  "id": "uuid",
  "url": "https://yourapp.com/api/webhooks/posthawk",
  "secret": "whsec_...",
  "events": ["delivery", "bounce", "complaint", "open", "click"],
  "enabled": true,
  "description": "Updated production webhook",
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-03-15T12:00:00Z"
}

POST/v1/webhooks/:id/testAPI Key

Send a test event to the webhook endpoint to verify it is reachable and correctly configured.

Parameter	Type	In	Description
`id`required	`string`	path	Webhook endpoint UUID

Response

json

{
  "success": true,
  "status": 200,
  "body": "OK"
}

DELETE/v1/webhooks/:idAPI Key

Delete a webhook endpoint. It will immediately stop receiving events.

Parameter	Type	In	Description
`id`required	`string`	path	Webhook endpoint UUID

Response

json

{
  "success": true
}

Domains

SMTP Relay