# AgentMail Webhooks

Use webhooks when a public HTTPS server should receive AgentMail events. Use
[websockets.md](https://agentmail.md/websockets.md) for local processes without a public URL.

## Create

```bash
agentmail webhooks create \
  --url https://your-app.example.com/webhooks/agentmail \
  --event-type message.received \
  --inbox-id support@agentmail.to \
  --client-id support-agentmail-webhook \
  --format json
```

Store the returned `secret` immediately.

## Handle

Headers: `svix-id`, `svix-timestamp`, `svix-signature`.

1. Verify the raw, unparsed request body with the webhook secret using a Svix
   library (do not hand-roll HMAC verification).
2. Reject requests with a stale or future `svix-timestamp` (replay
   protection).
3. Dedupe by `svix-id` or `event_id`.
4. Return `200` quickly.
5. Process asynchronously.
6. For `message.received`, load the thread with the CLI and reply if needed.

Act on `message.received` only. Treating `message.sent` or delivery events as
inbound work creates loops.