Webhooks

This page covers the webhook management API — creating, listing, updating, and rotating secrets on webhook endpoints. For event types, payload shape, and signature verification, see the Webhooks guide.

List webhooks

GET /webhooks
Authorization: Bearer <key>

[
  {
    "id": "...",
    "url": "https://yourapp.com/webhooks/ampout",
    "event_filters": ["enrollment.replied", "enrollment.bounced"],
    "disabled_at": null,
    "consecutive_failures": 0,
    "created_at": "..."
  }
]

secret is never returned by GET. If you’ve lost a secret, rotate it.

Create a webhook

POST /webhooks
Authorization: Bearer <key>
Content-Type: application/json
Idempotency-Key: optional-stable-key

{
  "webhook": {
    "url": "https://yourapp.com/webhooks/ampout",
    "event_filters": ["*"]
  }
}

Field	Required	Default	Notes
url	yes	—	Must be http:// or https://.
event_filters	no	["*"]	Array of event-type strings. ["*"] matches all. See event types.

Response

{
  "id": "...",
  "url": "https://yourapp.com/webhooks/ampout",
  "event_filters": ["*"],
  "disabled_at": null,
  "consecutive_failures": 0,
  "created_at": "...",
  "secret": "whsec_..."
}

The secret is one-shot — never returned again. Save it now.

Update a webhook

PATCH /webhooks/:id
Content-Type: application/json

{ "webhook": { "url": "https://newurl.example.com/h", "event_filters": ["enrollment.replied"], "disabled_at": null } }

Set disabled_at: null to re-enable an auto-disabled webhook. Updates do not rotate the secret.

Rotate the secret

POST /webhooks/:id/rotate_secret
Authorization: Bearer <key>

{ "id": "...", "secret": "whsec_..." }

The new secret is returned only here. Old signatures stop verifying immediately — coordinate the rotation with your receiver.

Delete a webhook

DELETE /webhooks/:id

Cascades to all the webhook’s deliveries.

List recent deliveries

GET /webhooks/:id/deliveries?limit=100

[
  {
    "id": "...",
    "event_type": "enrollment.replied",
    "attempt": 1,
    "status_code": 200,
    "error": null,
    "delivered_at": "2026-04-28T10:15:00Z",
    "created_at": "2026-04-28T10:15:00Z"
  },
  {
    "id": "...",
    "event_type": "enrollment.bounced",
    "attempt": 3,
    "status_code": 500,
    "error": null,
    "delivered_at": null,
    "created_at": "2026-04-28T10:14:00Z"
  }
]

attempt is the retry count (1 = first try, 2 = first retry, etc.). One delivery per HTTP attempt — a failed delivery that retries 3 times produces 3 rows for the same event. Default limit is 100; max 1000.

Errors

Status	Code	When
404	webhook_not_found	Unknown id or another account’s.
422	validation_failed	Bad URL format or invalid event_filters.