Create a webhook

curl -X POST https://api.middesk.com/v1/webhooks \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "url": "https://example.com/webhooks/middesk",
  "enabled_events": [
    "business.created",
    "business.updated",
    "order.updated"
  ],
  "secret": "whsec_abcdef123456",
  "event_schemas": [
    {
      "namespace": "business.updated",
      "schema": "{ id name runs { id agent } }"
    }
  ]
}'

{
  "created_at": "2025-01-07T12:00:00.000Z",
  "enabled_events": [
    "business.created",
    "business.updated",
    "order.updated"
  ],
  "event_schemas": [
    {
      "created_at": "2025-01-07T12:00:00.000Z",
      "id": "3f2a1c9e-8b4d-4e21-9c77-1a2b3c4d5e6f",
      "namespace": "business.updated",
      "object": "webhook_event_schema",
      "schema": "{ id name runs { id agent } }",
      "updated_at": "2025-01-07T12:00:00.000Z"
    }
  ],
  "id": "f2a3b4c5-d6e7-8901-5678-9abcdef01234",
  "object": "webhook",
  "updated_at": "2025-01-07T12:00:00.000Z",
  "url": "https://example.com/webhooks/middesk"
}

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.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

urlstringRequired

Webhook endpoint URL

enabled_eventslist of stringsRequired

Array of event types to subscribe to, or [”*”] for all events

secretstringOptional

Secret for webhook signature verification

event_schemaslist of objectsOptional

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.

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.

oidc_auth_methodenumOptional

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 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.

Allowed values:

oidc_client_idstringOptional

OIDC client ID. Required for both auth methods.

oidc_client_secretstringOptional

OIDC client secret. Required when oidc_auth_method is ‘client_secret’. Write-only; never returned in responses.

oidc_token_endpointstringOptional

OIDC token endpoint URL. Required for both auth methods.

oidc_resource_uristringOptional

Optional. OIDC resource URI (Microsoft-specific; use oidc_scope for standard OAuth 2.0).

oidc_scopestringOptional

Optional. OAuth 2.0 scope for the token request (e.g. “api://<app-id>/.default”).

oidc_access_token_ttl_secondsintegerOptional

OIDC access token TTL in seconds. Required for both auth methods.

Response

webhook created with wildcard events

Errors

422

Create Webhook Request Unprocessable Entity Error