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

# Create a webhook

`POST /v1/webhooks`

Creates a webhook endpoint. Optional event_schemas may be supplied at creation time to customize `data.object` for supported event namespaces while preserving the normal webhook envelope.

## Headers

- `Authorization` string, required

## Request body

- object
  - `url` string, required — Webhook endpoint URL
  - `secret` string — Secret for webhook signature verification
  - `enabled_events` string[], required — Array of event types to subscribe to, or ["*"] for all events
  - `event_schemas` TypeWebhooksWebhookCreateParamEventSchemasItem[] — Optional event schema overrides to create with the webhook. Event schemas customize only the delivered webhook payload's `data.object` for supported event namespaces. The webhook envelope fields are unchanged. After the webhook is created, manage event schemas through /v1/webhooks/{webhook_id}/event_schemas.
    - `namespace` string, required — Event namespace for the schema override. Currently supported business event namespaces are business.created and business.updated.
    - `schema` string, required — GraphQL selection set rooted at the event object for the namespace. For business.updated, write fields directly against the Business object, for example "{ id name runs { id agent } }". Use snake_case field names; do not wrap the query in "object { ... }".
  - `oidc_auth_method` 'private_key_jwt' | 'client_secret' — OIDC authentication method for obtaining access tokens. Required when configuring OIDC. 'private_key_jwt' — requires oidc_client_id, oidc_token_endpoint, oidc_access_token_ttl_seconds. 'client_secret' — requires oidc_client_id, oidc_client_secret, oidc_token_endpoint, oidc_access_token_ttl_seconds. Both methods optionally accept oidc_scope and oidc_resource_uri.
  - `oidc_client_id` string — OIDC client ID. Required for both auth methods.
  - `oidc_client_secret` string — OIDC client secret. Required when oidc_auth_method is 'client_secret'. Write-only; never returned in responses.
  - `oidc_token_endpoint` string — OIDC token endpoint URL. Required for both auth methods.
  - `oidc_resource_uri` string — Optional. OIDC resource URI (Microsoft-specific; use oidc_scope for standard OAuth 2.0).
  - `oidc_scope` string — Optional. OAuth 2.0 scope for the token request (e.g. "api://<app-id>/.default").
  - `oidc_access_token_ttl_seconds` integer — OIDC access token TTL in seconds. Required for both auth methods.

## Response `201`

webhook created with wildcard events

- unknown

## Other responses

- `422` — invalid request

---

[API](https://skmtc.net/middesk/apis/middesk-api.md) · [All operations](https://skmtc.net/middesk/apis/middesk-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/middesk/middesk-api/revisions/9882e52b445b/schema)