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

# Create webhook subscription

`POST /api/v1/webhooks`

## Request

- Base URL: `https://orchestrator.getaxonflow.com`
- URL: `https://orchestrator.getaxonflow.com/api/v1/webhooks`
- Auth: none declared
- TypeScript: <https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/docs/api/v1/webhooks/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new webhook subscription to receive real-time event notifications.
Events are delivered as HTTP POST requests to the specified URL with HMAC-SHA256
signatures when a secret is provided.

## Request body

- CreateWebhookRequest
  - `url` string, uri, required: URL to receive webhook event payloads
  - `events` string[], required: List of event types to subscribe to. Available events: - `policy.violation` — Policy violation detected - `policy.created` / `policy.updated` / `policy.deleted` — Policy lifecycle - `workflow.completed` / `workflow.failed` / `workflow.aborted` — Workflow lifecycle - `workflow.approval_required` — Step requires human approval - `budget.threshold_reached` / `budget.exceeded` / `budget.blocked` — Budget alerts - `plan.completed` / `plan.failed` — Plan lifecycle
  - `secret` string: Secret key for HMAC-SHA256 signature verification of webhook payloads
  - `active` boolean: Whether the subscription is active

## Response `201`

Webhook subscription created

- WebhookSubscription: A webhook subscription for receiving event notifications
  - `id` string: Unique subscription identifier
  - `url` string, uri: URL that receives webhook event payloads
  - `events` string[]: Event types this subscription listens for
  - `active` boolean: Whether the subscription is currently active
  - `tenant_id` string: Tenant ID that owns this subscription
  - `org_id` string: Organization ID that owns this subscription
  - `secret` string: Secret key for HMAC-SHA256 signature verification
  - `created_at` string, date-time: When the subscription was created
  - `updated_at` string, date-time: When the subscription was last updated

## Other responses

- `400`: Invalid request

---

[API](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api.md) - [All operations](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/revisions/f408ef3ec9dd?raw)