---
title: "Create a webhook"
method: POST
path: "/webhooks"
tags: ["Webhooks"]
---

# Create a webhook

`POST /webhooks`

Create a webhook endpoint to receive email event notifications.

**Available events:**
- `MessageSent` - Email accepted by recipient server
- `MessageDeliveryFailed` - Delivery permanently failed
- `MessageDelayed` - Delivery temporarily failed, will retry
- `MessageBounced` - Email bounced
- `MessageHeld` - Email held for review
- `MessageLinkClicked` - Recipient clicked a link
- `MessageLoaded` - Recipient opened the email
- `DomainDNSError` - Domain DNS issue detected

## Request body

- CreateWebhookRequest
  - `name` string, required — Webhook name for identification
  - `url` string, uri, required — HTTPS endpoint URL
  - `events` string[], nullable — Events to subscribe to (accepts null): - `MessageSent` - Email successfully delivered to recipient's server - `MessageDelayed` - Temporary delivery failure, will retry - `MessageDeliveryFailed` - Permanent delivery failure - `MessageHeld` - Email held for manual review - `MessageBounced` - Email bounced back - `MessageLinkClicked` - Recipient clicked a tracked link - `MessageLoaded` - Recipient opened the email (tracking pixel loaded) - `DomainDNSError` - DNS configuration issue detected
  - `allEvents` boolean, nullable — Subscribe to all events (ignores events array, accepts null)
  - `enabled` boolean, nullable — Whether the webhook is enabled (accepts null)

## Response `200`

Webhook created

- WebhookResponse
  - `success` true, required
  - `data` object, required
    - `id` string, required — Webhook ID
    - `uuid` string, uuid, required
    - `name` string, required — Webhook name for identification
    - `url` string, uri, required — Webhook endpoint URL
    - `events` string[], required — Subscribed events
    - `allEvents` boolean, required — Whether subscribed to all events
    - `enabled` boolean, required — Whether the webhook is active
    - `createdAt` string, date-time, required
  - `meta` ApiMeta, required
    - `requestId` string, required — Unique request identifier for debugging and support

## Other responses

- `400` — Invalid request parameters
- `401` — Invalid or missing API key
- `500` — Internal server error

## Changes

- **2026-01-22** `b8e976f80ad3` — 2 warning, 2 info
  - added the new `SendLimitApproaching` enum value to the `data/events/items/` response property for the response status `200`
  - added the new `SendLimitExceeded` enum value to the `data/events/items/` response property for the response status `200`
  - added the new `SendLimitApproaching` enum value to the request property `events/items/`
  - added the new `SendLimitExceeded` enum value to the request property `events/items/`

[Change history](https://skmtc.dev/arkhq-io/apis/ark-email-api/changes/webhooks/post.md)

---

[API](https://skmtc.dev/arkhq-io/apis/ark-email-api.md) · [All operations](https://skmtc.dev/arkhq-io/apis/ark-email-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/arkhq-io/ark-email-api/revisions/2cfd9423fd8a/schema)