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

# Create a webhook endpoint

`POST /webhooks`

## Request

- Base URL: `https://www.unitpost.com/api/v1`
- URL: `https://www.unitpost.com/api/v1/webhooks`
- Auth: HTTP bearer

Register an `https` URL to receive event notifications (deliveries, bounces, opens, clicks, and more) and choose which events it subscribes to. The response includes the `signing_secret` exactly once — store it now, as it can never be retrieved again; use it to verify each delivery's signature. Confirm the endpoint works with [Send a test event](#post-webhooks-id-test), and adjust its URL or events later with [Update a webhook endpoint](#patch-webhooks-id). Requires the `webhooks:manage` capability.

## Request body

- WebhookCreate
  - `url` string, required
  - `events` string[], required
  - `name` string

## Response `201`

Created — includes the one-time signing secret.

- WebhookCreated
  - `object` 'webhook', required
  - `id` string, required
  - `name` string, required
  - `url` string, required
  - `events` string[], required
  - `status` 'enabled' | 'disabled' | 'suspended', required
  - `created_at` string, required
  - `updated_at` string, required
  - `signing_secret` string, required: The HMAC signing secret. Shown exactly once — store it now; it can never be retrieved again. Use it to verify the signature on every delivery to this endpoint.

## Other responses

- `401`: Missing or invalid API key.
- `403`: Insufficient scope.
- `409`: That URL or name is already used by another endpoint.
- `422`: Validation error (bad URL, unknown event, an event category not yet available on this workspace such as `sms.*`, or limit reached).

---

[API](https://skmtc.dev/unitpost/apis/unitpost-api.md) · [All operations](https://skmtc.dev/unitpost/apis/unitpost-api/llms.txt) · [OpenAPI document](https://skmtc.dev/unitpost/apis/unitpost-api/revisions/86ff7c890967?raw)