# Webhooks API

See the narrative [Webhooks](/webhooks) guide for verification code and the full event list.

## Create

`POST /api/practices/{id}/webhooks`

```json
{
  "name": "ops",
  "url": "https://example.com/hooks/werkmail",
  "events": [
    "message.created",
    "message.sent",
    "message.delivered",
    "message.hard_bounced",
    "message.soft_bounced",
    "message.spam_complaint",
    "message.suppressed",
    "message.failed",
    "message.content_blocked",
    "suppression.added",
    "suppression.removed"
  ]
}
```

Response includes `secret` once (`whsec_…`). HTTPS only.

## List / delete / test / deliveries

| Method | Path |
| --- | --- |
| `GET` | `/api/practices/{id}/webhooks` |
| `DELETE` | `/api/practices/{id}/webhooks/{webhookID}` |
| `POST` | `/api/practices/{id}/webhooks/{webhookID}/test` |
| `GET` | `/api/practices/{id}/webhooks/{webhookID}/deliveries` |

## Signature

`X-Werkmail-Signature` = hex HMAC-SHA256 of `{timestamp}.{raw-body}` with the webhook secret. Timestamp is `X-Werkmail-Timestamp` (unix seconds). Event name is `X-Werkmail-Event`.

Envelope:

```json
{ "id": "…", "event": "message.delivered", "timestamp": "…", "data": { } }
```

Suppression payloads include `scope`, `project_id`, `route_id`, and slugs when available.

## Alerts

`POST /api/practices/{id}/alerts` — `{ "name", "kind": "slack"|"teams", "url" }`.  
`POST …/alerts/{id}/test`, `DELETE …/alerts/{id}`, `GET …/alerts`.