---
title: "Create webhook endpoint"
method: POST
path: "/v2/organizations/{organizationId}/webhooks"
tags: ["Webhooks"]
---

# Create webhook endpoint

`POST /v2/organizations/{organizationId}/webhooks`

## Request

- Base URL: `https://api.pdfs.build`
- URL: `https://api.pdfs.build/v2/organizations/{organizationId}/webhooks`
- Auth: HTTP bearer

Registers a public http(s) URL. Non-global destinations (loopback, private, link-local, CGNAT and other reserved ranges, IPv4 and IPv6) are rejected at registration and re-validated before every delivery. The signing secret (`whsec_...`) is returned exactly once. Requires a paid plan.

## Request body

- CreateWebhookRequest
  - `url` string, uri, required: Public http(s) destination.
  - `description` string
  - `enabled` boolean

## Response `201`

The endpoint and its secret.

- WebhookEndpointWithSecret
  - `endpoint` WebhookEndpoint, required
    - `id` string, required
    - `organizationId` string, required
    - `url` string, uri, required
    - `enabled` boolean, required
    - `description` string, nullable, required
    - `createdAt` string, required: UTC, ISO 8601 without a timezone suffix.
    - `updatedAt` string, required: UTC, ISO 8601 without a timezone suffix.
  - `secret` string, required: Standard Webhooks signing secret (`whsec_` + base64). Shown once; store it now.

## Other responses

- `400`: `invalid_url` (not a well-formed http(s) URL) or `url_not_allowed` (resolves to a non-public address).
- `401`: Missing, invalid or expired API key.
- `403`: `plan_gated` (webhooks need a paid plan) or `organization_scope_mismatch`.

---

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