---
title: "Create Webhook Subscription"
method: POST
path: "/webhooks/subscribe"
tags: ["Document AI — Webhooks"]
---

# Create Webhook Subscription

`POST /webhooks/subscribe`

## Request

- Base URL: `https://api.paperoffice.ai/latest`
- URL: `https://api.paperoffice.ai/latest/webhooks/subscribe`
- Auth: HTTP bearer

po_webhooks_subscribe: Create a new webhook subscription. Payloads are signed with HMAC-SHA256. Response includes id and subscription_id (same value) — save either for po_webhooks_test, po_webhooks_update, po_webhooks_delete. Auto...

## Request body

- object
  - `name` string, required: Display name for the subscription (required).
  - `url` string, required: Webhook target URL (HTTPS recommended).
  - `events` string[], required: Event types, e.g. ["document.uploaded","document.edited"], or ["*"] for all. Full list: see the tool description.
  - `secret` string: HMAC secret (auto-generated if empty).
  - `filters` object: Optional Filter (e.g. workspace_id, pofid)
  - `headers` object: Additional HTTP headers as key-value pairs
  - `retry_policy` 'none' | 'linear' | 'exponential': Retry policy: none, linear, or exponential (default: exponential).
  - `max_retries` integer: Maximum delivery retries after failure (0–10, default 5).
  - `timeout_ms` integer: Timeout in ms (1000-30000, default: 10000)
  - `is_active` boolean: Create the subscription active (true, default) or inactive (false). Accepts true/false, 1/0, yes/no, on/off (JSON boolean or form string); other values return 400 INVALID_BOOLEAN.

## Response `200`

Success

- object
  - `status` string, required
  - `id` integer, required: Subscription ID (canonical, same as subscription_id)
  - `subscription_id` integer, required: Alias for id — use for update/test/delete
  - `secret` string, required
  - `events` string[], required
  - `events_requested` string[]
  - `events_resolved` string[]
  - `message` string

## Other responses

- `4XX`: Error
- `5XX`: Error

---

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