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

# Create a webhook endpoint

`POST /api/v1/webhooks/endpoints`

Registers a URL to receive webhook events for your agency. The response includes the `signingSecret` used to verify delivery signatures — it is returned on create only. The first call automatically enables webhooks for the agency. `filterTypes` is required and must list at least one event type to deliver (see the Webhooks tag for the full list). An agency can have at most 50 endpoints — creating one past that cap returns `422` with the provider's limit message; delete an endpoint to free a slot.

## Request body

- object
  - `url` string, required — HTTPS URL Atlas delivers events to
  - `description` string — Human-readable label for the endpoint
  - `disabled` boolean — Disabled endpoints receive no deliveries
  - `filterTypes` string[], required — Event types to deliver to this endpoint. At least one is required

## Response `201`

Webhook endpoint created

- object
  - `status` 'ok', required
  - `data` object, required
    - `id` string, required — Webhook endpoint ID
    - `url` string, required — Delivery URL
    - `description` string, required — Human-readable label
    - `disabled` boolean, required — Disabled endpoints receive no deliveries
    - `filterTypes` string[], nullable, required — Event types delivered to this endpoint
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `signingSecret` string, required — HMAC secret for verifying deliveries. Returned on create only — store it now, it cannot be retrieved via the API later

## Other responses

- `401` — Unauthorized - missing or invalid API key
- `422` — Validation error - the request failed schema validation (`errors.fieldErrors`) or a business rule (`errors.formErrors`)
- `429` — Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the "Rate limits" section of the introduction for details.

## Changes

- **2026-10-03** `cd4bc8bbd95e` — 1 info
  - added the optional property `error` to the response with the `422` status
- **2026-09-29** `d7ef7f970d5b` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/recruitwithatlas/apis/atlas-api/changes/api/v1/webhooks/endpoints/post.md)

---

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