---
title: "Register a webhook (signing secret is shown once)"
method: POST
path: "/api/v2/webhooks"
tags: ["v2 Webhooks"]
---

# Register a webhook (signing secret is shown once)

`POST /api/v2/webhooks`

## Request

- Base URL: `https://pdf2md.dev`
- URL: `https://pdf2md.dev/api/v2/webhooks`
- Auth: one of:
  - API key in cookie `p2m_session`
  - HTTP bearer

EP-023-T10. The server generates a signing secret whsec_… (returned ONCE), used to sign deliveries (X-P2M-Signature). url must be https and public (SSRF-guard). events — filter (empty = all). 403 if the tier has no webhooks_enabled or the tier's endpoint limit is reached.

## Request body

- V2WebhookCreateRequest
  - `url` string, uri, required: https, public host (SSRF-guard)
  - `events` string[]: empty = subscribe to all events
  - `description` string

## Response `201`

Created

- V2WebhookCreated
  - `id` string, uuid, required
  - `url` string, uri, required
  - `events` string[], required: subscribed events; [] = all
  - `description` string
  - `enabled` boolean, required
  - `failure_count` integer: consecutive failed exhausted deliveries
  - `last_delivery_at` string, date-time, nullable
  - `created_at` string, date-time
  - `secret` string, required: Signing secret (whsec_…) for X-P2M-Signature — shown ONCE

## Other responses

- `400`: Invalid url/events
- `401`: Missing/invalid API key or session
- `403`: Webhooks unavailable on the tier or limit reached

---

[API](https://skmtc.dev/pdf2md/apis/pdf-to-markdown-api-facade.md) · [All operations](https://skmtc.dev/pdf2md/apis/pdf-to-markdown-api-facade/llms.txt) · [OpenAPI document](https://skmtc.dev/pdf2md/apis/pdf-to-markdown-api-facade/revisions/4636782fb8b6?raw)