---
title: "Create a webhook"
method: POST
path: "/v2/webhooks"
tags: ["Webhooks"]
---

# Create a webhook

`POST /v2/webhooks`

Creates a webhook that delivers the selected workspace events to an HTTPS endpoint. Generate a signing secret first with `GET /v2/webhooks/secret`.

## Request body

- CreateWebhookRequest — Configuration used to create a webhook in the current workspace.
  - `_id` string, required — Client-generated webhook ID.
  - `url` string, uri, required — HTTPS endpoint that receives webhook deliveries.
  - `content_type` 'application/json' | 'application/x-www-form-urlencoded', required — Content type sent with webhook deliveries.
  - `display_name` string, required — Human-readable webhook name.
  - `events` string[], required — One or more workspace event slugs that trigger a delivery, for example `deployment.invoked` or `llm.response`.
  - `secret` string, required — Signing secret returned by `GET /v2/webhooks/secret`. Deliveries set `X-Orq-Signature` to the lowercase hexadecimal HMAC-SHA256 of the exact request body bytes.
  - `enabled` boolean — Whether webhook deliveries are enabled.

## Response `200`

OK

- Webhook — A webhook subscription and its delivery configuration. Responses include the signing secret; treat it as sensitive.
  - `_id` string, required — Unique webhook ID.
  - `url` string, uri, required — HTTPS endpoint that receives webhook deliveries.
  - `content_type` 'application/json' | 'application/x-www-form-urlencoded', required — Content type sent with webhook deliveries.
  - `display_name` string, required — Human-readable webhook name.
  - `events` string[], required — Workspace event slugs that trigger a delivery, for example `deployment.invoked` or `llm.response`.
  - `secret` string, required — Signing secret used to compute `X-Orq-Signature` as the lowercase hexadecimal HMAC-SHA256 of the exact request body bytes. Treat this value as sensitive.
  - `enabled` boolean — Whether webhook deliveries are enabled.
  - `failure_count` integer — Server-managed number of consecutive delivery failures.
  - `created_by_id` string, required — Account ID that created the webhook.
  - `updated_by_id` string, required — Account ID that most recently updated the webhook.
  - `created` string, date-time, required — Creation time in RFC 3339 format.
  - `updated` string, date-time, required — Most recent update time in RFC 3339 format.

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/versions/1072e5ba28ab/schema)