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

# Create a webhook

`POST /tenants/{tenantId}/webhooks`

Create a webhook endpoint to receive email event notifications for a tenant.

**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

## Path parameters

- `tenantId` string, required

## 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 `201`

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
- `404` — Tenant not found
- `429` — Rate limit exceeded
- `500` — Internal server error

---

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