Skip to content

Create a webhook endpoint

Creates an endpoint. The URL must pass the destination policy (HTTPS, public host, no private ranges). The `whsec_` signing secret is returned **once**.

POST
/v1/webhook-endpoints

Creates an endpoint. The URL must pass the destination policy (HTTPS, public host, no private ranges). The whsec_ signing secret is returned once.

Authorization

AuthorizationBearer <token>

OAuth 2.0 client credentials. private_key_jwt (SMART Backend Services asymmetric) is recommended; client secrets need an IP allowlist or mTLS outside the sandbox.

In: header

Scope: webhooks:write

Header Parameters

Api-Version?enum

Overrides the app's pinned dated version for this request.

Idempotency-Key?string

1–255 characters of [A-Za-z0-9._:-] (a UUID v4 is recommended); never PHI. Stored 24 hours per app.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/v1/webhook-endpoints" \  -H "Content-Type: application/json" \  -d '{    "eventTypes": [      "request.created"    ],    "url": "https://10.0.0.5/hooks"  }'
{  "apiVersion": "string",  "auth": {    "clientId": "string",    "clientSecretSet": true,    "kind": "none",    "mtls": true,    "tokenUrl": "string"  },  "createdAt": "2026-09-14T15:00:11.402Z",  "description": "string",  "eventTypes": [    "string"  ],  "headers": [    {      "name": "string",      "valueSet": true    }  ],  "health": {    "circuit": "closed",    "consecutiveFailures": -9007199254740991,    "failingSince": "2026-09-14T15:00:11.402Z",    "successRate24h": 0  },  "id": "we_k57a1x2m9q4t8v3w5x1y6z7a8b9c0d1e",  "includeNewEventTypes": true,  "object": "webhook_endpoint",  "secret": {    "previousVersionExpiresAt": "2026-09-14T15:00:11.402Z",    "value": "string",    "version": -9007199254740991  },  "sites": [    "kb-main-ed"  ],  "status": "enabled",  "updatedAt": "2026-09-14T15:00:11.402Z",  "url": "string",  "version": -9007199254740991}

Was this page helpful?