---
title: "Creates a webhook endpoint for the authenticated account and returns its signing secret in the response body."
method: POST
path: "/api/webhooks"
tags: ["webhooks"]
---

# Creates a webhook endpoint for the authenticated account and returns its signing secret in the response body.

`POST /api/webhooks`

## Request

- Base URL: `https://api.pricklymails.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pricklymails.com/api/webhooks`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

## Request body

- CreateWebhookRequest: `POST /api/webhooks` request body.
  - `description` string, nullable: Free-text description of the endpoint.
  - `events` string[], required: Events to subscribe to, for example `"job.completed"` or `"job.failed"`. At least one is required.
  - `url` string, required: HTTPS URL that receives event notifications (at most 2048 characters, no private or loopback address).

## Response `201`

Endpoint created; `secret` is shown once.

- CreateWebhookResponse: Metadata of a webhook endpoint, returned when listing, reading or updating endpoints.
  - `consecutive_failures` integer, required: Number of failed deliveries in a row since the last success.
  - `created_at` string, required: RFC 3339 creation timestamp.
  - `description` string, nullable: Description of the endpoint, omitted when none was set.
  - `events` string[], required: Events the endpoint is subscribed to.
  - `last_delivery_at` string, nullable: RFC 3339 timestamp of the last delivery, omitted when there was none.
  - `status` string, required: Status of the endpoint: `"active"`, `"paused"` or `"disabled"`.
  - `successful_deliveries` integer, required: Number of deliveries the endpoint acknowledged with a 2xx status.
  - `total_deliveries` integer, required: Number of deliveries attempted.
  - `url` string, required: URL that receives the notifications.
  - `uuid` string, required: Public UUID of the endpoint.
  - `secret` string, required: The signing secret, hex-encoded. It is returned only once, so store it securely.

## Other responses

- `400`: Invalid url, events, or empty events list.
- `401`: Missing or invalid API key, session token, or agent token.
- `403`: Plan webhook-endpoint limit reached, or the key or agent token lacks the `webhooks:create` scope.

---

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