Skip to main content

Create a webhook subscription

POST 
/api/v1/webhooks/create-subscription

Creates a new event subscription on an existing webhook endpoint. The subscription filters events by the specified event types and delivers matching events to the endpoint URL.

One subscription per endpoint​

Section ID: DOC-IN-webhooks-api-createWebhookSubscription#one-subscription-per-endpoint

Only one live subscription is allowed per endpoint; a second fails with ALREADY_EXISTS. There is no public update-subscription operation. Delete the old subscription and create its replacement when a delivery gap is acceptable.

The following access conditions are preserved as declared intent and are not implemented by generated code: Tenant request context, Tenant-scoped webhook ownership.

Use this in a guide: Event catalog · Receive a completed order summary in your backend

Request​

Responses​

Subscription created successfully

Subscribe an existing endpoint that does not already have a live subscription.​

Section ID: DOC-IN-webhooks-api-createWebhookSubscription#example-webhooks-createWebhookSubscription-request

Request example

{
  "endpointId": "ep_abc123",
  "eventTypes": [
    "llm.generation_completed"
  ]
}

Illustrative response shape; omitted default fields and actual outcomes depend on the operation.​

Section ID: DOC-IN-webhooks-api-createWebhookSubscription#example-webhooks-createWebhookSubscription-response

Response example

{
  "subscription": {
    "id": "example_123",
    "name": "example",
    "endpointId": "https://example.com/resource",
    "eventTypes": [
      "example"
    ],
    "filter": {},
    "retryConfig": {
      "strategy": "RETRY_STRATEGY_LINEAR",
      "retryCount": 1,
      "intervalSeconds": 1
    },
    "createdAt": "2026-09-16T12:00:00Z",
    "externalId": "example_123",
    "updatedAt": "2026-09-16T12:00:00Z"
  }
}

Document ID: DOC-IN-webhooks-api-createWebhookSubscription. Section identities and revisions.

SectionStable reference
Create a webhook subscriptionDOC-IN-webhooks-api-createWebhookSubscription#overview
RequestDOC-IN-webhooks-api-createWebhookSubscription#request
ResponsesDOC-IN-webhooks-api-createWebhookSubscription#responses