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

# Create a webhook endpoint

`POST /v1/webhooks`

## Request

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

Registers an HTTPS endpoint. Endpoints receive every event type (`message.received`, `sms.received`, `domain.verified`, `endpoint.test`) — there is no per-endpoint event filter — and payloads never contain message bodies. Deliveries are signed `X-MailFixture-Signature: t=<unix>,v1=<hmac-sha256>` with the endpoint's secret; 8 attempts with backoff, and 5 consecutively exhausted deliveries auto-disable the endpoint.

## Request body

- CreateWebhookRequest
  - `description` string: Optional; blank is treated as none.
  - `url` string, uri, required: Must be https and resolve to a public IP.

## Response `201`

Endpoint created — save `secret` now; lists only ever show a hint.

- WebhookCreated
  - `created_at` string, date-time, required
  - `description` string, nullable, required
  - `id` string, uuid, required
  - `secret` string, required: Signing secret (`whsec_…`) — shown exactly once; lists only carry a hint.
  - `url` string, required

## Other responses

- `400`: URL refused: not https, credentials or whitespace in the URL, unresolvable host, or the host is not a public IP.
- `401`: Missing bearer token, malformed key, or unknown/revoked/invalid API key.
- `403`: Webhooks require a paid plan, or the plan's endpoint cap is reached (solo 3, team 10, scale 25).
- `409`: An endpoint with this URL already exists.
- `429`: Per-key rate limit exceeded. `Retry-After` says when the next request will be admitted; the RateLimit headers name the bucket that refused (`requests` or `creates`) with `r=0`.
- `500`: Unexpected server error. `detail` is null — internals are never leaked.

---

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