---
title: Webhook Setup
description: Set up webhooks to receive real-time notifications.
surface: shared
---

## Create a Webhook

```bash
curl -X POST https://api.agentry.to/agent/v0/webhooks \
  -H "Authorization: Bearer ag_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhook",
    "event_types": ["message.received", "message.bounced"]
  }'
```

## Handle Webhook Events

Your endpoint should:

1. Return a `200` status code quickly
2. Process the event asynchronously if needed
3. Handle duplicate deliveries (webhooks may retry)

```typescript
app.post("/webhook", (req, res) => {
  const event = req.body;

  switch (event.event) {
    case "message.received":
      // Process inbound email
      handleInboundEmail(event.data);
      break;
    case "message.bounced":
      // Mark the recipient suppressed or notify your team.
      handleBounce(event.data);
      break;
  }

  res.status(200).send("OK");
});
```

## Managing Webhooks

- **List:** `GET /agent/v0/webhooks`
- **Update:** `PATCH /agent/v0/webhooks/{webhook_id}`
- **Delete:** `DELETE /agent/v0/webhooks/{webhook_id}`
- **Scope updates:** `PATCH /agent/v0/webhooks/{webhook_id}` with `add_inbox_ids`, `remove_inbox_ids`, `add_pod_ids`, `remove_pod_ids`