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

# Create a platform webhook

`POST /platform/webhooks`

Create a platform webhook to receive email event notifications from all tenants.

Platform webhooks receive events from **all tenants** in your organization.
Each webhook payload includes a `tenant_id` field to identify which tenant
the event belongs to.

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

**Webhook payload includes:**
- `event` - The event type
- `tenant_id` - The tenant that sent the email
- `timestamp` - Unix timestamp of the event
- `payload` - Event-specific data (message details, status, etc.)

## Request body

- CreatePlatformWebhookRequest
  - `name` string, required — Display name for the webhook
  - `url` string, uri, required — Webhook endpoint URL (must be HTTPS)
  - `events` string[] — Events to subscribe to. Empty array means all events.

## Response `201`

Platform webhook created

- PlatformWebhookResponse
  - `success` true, required
  - `data` object, required
    - `id` string, required — Platform webhook ID
    - `name` string, required — Webhook name for identification
    - `url` string, uri, required — Webhook endpoint URL
    - `events` string[], required — Subscribed events (empty = all events)
    - `enabled` boolean, required — Whether the webhook is active
    - `createdAt` string, date-time, required
    - `updatedAt` 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
- `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)