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

Supported event types:

Email delivery events:
• send — email queued for sending via SES
• delivery — successfully delivered
• bounce — bounced (use `event_data.bounce.bounceType` to distinguish Permanent/Transient/Undetermined)
• complaint — recipient marked as spam
• reject — SES rejected at submission time
• delivery_delay — temporarily delayed but not yet a bounce
• open — recipient opened the email (tracking pixel hit)
• click — recipient clicked a link in the email

Newsletter events (cloud + self-hosted):
• newsletter.subscriber.created — pending subscriber created (DOI confirmation email sent)
• newsletter.subscriber.confirmed — subscriber clicked the confirm link, or signed up with DOI off
• newsletter.subscriber.unsubscribed — subscriber unsubscribed (manually, via auto-suppress, or via the public unsubscribe link)
• newsletter.issue.sent — issue finished fanning out to subscribers
• newsletter.issue.failed — issue send aborted with an error

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

### Verification snippets

**Node.js:**

```js
const crypto = require('crypto');

function verifyWebhook(req, secret) {
  const body = JSON.stringify(req.body); // or use raw-body middleware
  const signature = req.headers['x-posthawk-signature'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
```

**Python:**

```python
import hmac, hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(signature, expected)
```

**Go:**

```go
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

func VerifyWebhook(body []byte, signature, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(signature), []byte(expected))
}
```

Retry behavior:

• Failed deliveries (non-2xx response or timeout) are retried with exponential backoff
• Each delivery attempt is logged in `webhook_deliveries` and visible in the dashboard
• Permanent failures stop retrying after the configured max attempts
• Test endpoints with `POST /v1/webhooks/:id/test` to verify before going live

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.