Managing endpoints

Base URL: https://app.example.com/api/v1/workspace-webhooks Authenticate with a workspace API key. Older credentials (sbk_ keys, personal tokens) and browser sessions are not accepted here.

Permissions

Request	Needs
`GET /events`, `GET /endpoints`, `GET /endpoints/{endpoint}`	`webhooks:read`
`POST /endpoints`, `PATCH /endpoints/{endpoint}`, `DELETE /endpoints/{endpoint}`	`webhooks:write`
`POST /endpoints/{endpoint}/rotate-secret`	`webhooks:write`
`POST /endpoints/{endpoint}/test`	`webhooks:deliveries:retry`
`GET /endpoints/{endpoint}/deliveries`, `GET /deliveries/{delivery}`	`webhooks:deliveries:read`
`POST /deliveries/{delivery}/resend`	`webhooks:deliveries:retry`

The key also needs publishing:webhooks:subscribe and/or salesbot:webhooks:subscribe for every product the endpoint subscribes to. Endpoints that include a product your key cannot subscribe to are left out of lists and refused on direct access.

Required headers

Header	When	Why
`Idempotency-Key`	Every `POST`	8–200 letters, digits, `.`, `_`, `:` or `-`. Retrying with the same key and the exact same body returns the original response (with `Idempotency-Replayed: true`) instead of acting twice. A different body with the same key returns `409`. Keys are remembered for 24 hours.
`If-Match: "<revision>"`	Every `PATCH`, `DELETE` and `POST` under `/endpoints/{endpoint}`	Take the revision from the `ETag` of `GET /endpoints/{endpoint}`. Missing returns `428`; out of date returns `412`.

List available events

curl https://app.example.com/api/v1/workspace-webhooks/events \
  -H "Authorization: Bearer osk_YOUR_SECRET"

Returns every event your workspace can subscribe to, with its data schema, a sample payload and the channels it supports.

Create an endpoint

curl -X POST https://app.example.com/api/v1/workspace-webhooks/endpoints \
  -H "Authorization: Bearer osk_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-crm-hook-001" \
  -d '{
    "name": "CRM notifications",
    "url": "https://example.com/webhooks",
    "enabled": false,
    "subscriptions": [
      {"event": "publishing.post.published", "channel": "all"},
      {"event": "salesbot.contact.created", "channel": "whatsapp"}
    ]
  }'

url must be public https://.
Publishing events always use "channel": "all".
New endpoints are always created paused, whatever you send in enabled. Enable it once your receiver is ready.
Returns 201 with the endpoint and its signing secret (whsec_...) in a top-level secret field. This is the only time the secret is returned. If the response is lost, retry with the same Idempotency-Key and body to get it again within 24 hours.
A workspace can have up to 25 endpoints.

Update an endpoint

curl -X PATCH https://app.example.com/api/v1/workspace-webhooks/endpoints/{endpoint} \
  -H "Authorization: Bearer osk_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "7"' \
  -d '{"enabled": true}'

Fields you leave out keep their current values. If you send subscriptions, it replaces the whole list.

Send a test event

curl -X POST https://app.example.com/api/v1/workspace-webhooks/endpoints/{endpoint}/test \
  -H "Authorization: Bearer osk_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-001" \
  -H 'If-Match: "7"' \
  -d '{"event": "publishing.post.published"}'

Sends a sample of a subscribed event with "test": true. The endpoint must be enabled. Returns 202 with the new delivery.

Rotate the signing secret

curl -X POST https://app.example.com/api/v1/workspace-webhooks/endpoints/{endpoint}/rotate-secret \
  -H "Authorization: Bearer osk_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rotate-001" \
  -H 'If-Match: "7"' \
  -d '{"immediate": false}'

"immediate": false keeps the old secret valid for 24 hours alongside the new one.
"immediate": true revokes the old secret straight away.
You cannot start a second overlapping rotation while one is in progress.

Delivery history and resend

curl https://app.example.com/api/v1/workspace-webhooks/endpoints/{endpoint}/deliveries \
  -H "Authorization: Bearer osk_YOUR_SECRET"

GET /deliveries/{delivery} shows its attempts. POST /deliveries/{delivery}/resend sends it again as a new delivery (with a new ID, linked through resend_of). Resending needs the endpoint to be enabled, still subscribed to the event, and the payload to still be stored. Payloads are kept for about 7 days.

Delete an endpoint

curl -X DELETE https://app.example.com/api/v1/workspace-webhooks/endpoints/{endpoint} \
  -H "Authorization: Bearer osk_YOUR_SECRET" \
  -H 'If-Match: "7"'

Returns 204.

Limits

Management changes are limited to 60 per workspace per minute, on top of the normal API rate limits.

Getting started

Webhooks

Integrations

Permissions

Required headers

List available events

Create an endpoint

Update an endpoint

Send a test event

Rotate the signing secret

Delivery history and resend

Delete an endpoint

Limits

​Permissions

​Required headers

​List available events

​Create an endpoint

​Update an endpoint

​Send a test event

​Rotate the signing secret

​Delivery history and resend

​Delete an endpoint

​Limits

Permissions

Required headers

List available events

Create an endpoint

Update an endpoint

Send a test event

Rotate the signing secret

Delivery history and resend

Delete an endpoint

Limits