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

# Register a webhook endpoint

`POST /webhooks`

## Request

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

Registers a URL that receives ALL events (post.published, post.partially_failed, post.failed, post.scheduled, account.unauthorized, image.completed, image.failed). Deliveries are HTTP POSTs with a WebhookEventPayload body, retried up to 5 times with exponential backoff. Each request includes `x-adaptly-signature`, `x-adaptly-timestamp`, `x-adaptly-event`, and `x-adaptly-webhook-id` headers. Webhooks are auto-disabled after 20 consecutive failed deliveries.. Requires the `webhooks.manage` permission.

## Headers

- `X-Workspace-Id` string

## Request body

- CreateWebhookRequest
  - `url` string, uri, required: Publicly reachable http(s) endpoint. Receives all events

## Response `201`

Created webhook (the only response that includes the signing secret)

- CreateWebhookResponse
  - `id` string
  - `url` string
  - `active` boolean
  - `createdAt` string, date-time
  - `updatedAt` string, date-time
  - `lastSuccessAt` string, date-time, nullable
  - `lastFailureAt` string, date-time, nullable
  - `disabledAt` string, date-time, nullable
  - `secret` string: HMAC-SHA256 signing secret (whsec_...) for the x-adaptly-signature header. Returned ONLY at creation, store it securely; if lost, delete and re-create the webhook

## Other responses

- `400`: Invalid URL or webhook limit reached
- `401`: Invalid or missing API key
- `403`: The key's role does not hold `webhooks.manage`
- `409`: A webhook with this URL already exists
- `429`: Rate limit exceeded

---

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