Change a webhook endpoint

PATCH /v1/webhooks/{id}

Changes the fields you send and keeps the others.

Needs webhooks:write.

Turn an endpoint off

curl -X PATCH https://app.soosh.io/v1/webhooks/4c6e8a0c-2e4b-4d6f-b8a0-1c3e5a7c9e4b \
  -H "Authorization: Bearer $SOOSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

const res = await fetch('https://app.soosh.io/v1/webhooks/4c6e8a0c-2e4b-4d6f-b8a0-1c3e5a7c9e4b', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SOOSH_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "enabled": false
  }),
});
console.log(await res.json());

import os
import requests

res = requests.patch(
    "https://app.soosh.io/v1/webhooks/4c6e8a0c-2e4b-4d6f-b8a0-1c3e5a7c9e4b",
    headers={"Authorization": f"Bearer {os.environ['SOOSH_API_KEY']}"},
    json={
        "enabled": False,
    },
)
print(res.json())

Response200

{
  "id": "4c6e8a0c-2e4b-4d6f-b8a0-1c3e5a7c9e4b",
  "url": "https://hooks.example.com/soosh",
  "description": "Order updates",
  "events": [
    "message.status",
    "contact.created"
  ],
  "headers": {
    "X-Api-Token": "********"
  },
  "status": "disabled",
  "disabled_reason": null,
  "paused_until": null,
  "previous_secret_expires_at": "2026-10-15T09:45:12.340Z",
  "created_at": "2026-10-14T09:20:05.631Z",
  "updated_at": "2026-10-14T11:02:44.190Z"
}

Every field of the webhook endpoint object

Path parameters

id string · uuid

The webhook endpoint’s ID.

Body

url string

A new https:// URL, with the same rules as when you create an endpoint.

description string

Up to 500 characters.

events array of strings

Any of message.received message.sent message.status contact.created contact.updated contact.deleted template.status chat.assigned chat.closed chat.reopened broadcast.status. At least 1 item.

headers object

Replaces all custom headers, with the same rules as when you create an endpoint. Send ******** as a value to keep the saved value.

A map; each value is a string. Up to 10 keys.

enabled boolean

false turns the endpoint off; true turns it back on.

Rules

The rules of POST /v1/webhooks apply to the endpoint as it will be. An event it already has stays, even if its feature has since left your plan. You need the read scope of every event it will send, including those.

Custom headers and a new URL

A url on another server (a different scheme, host or port) needs every header’s value sent again. A saved or ******** value is then 422 invalid_field on headers.<name>, so a saved value only goes to the server it was set for.

Pauses and ownership

A new url or new headers end a pause, and Soosh tries the endpoint again.

enabled: true turns a stopped endpoint back on, whoever stopped it. The key you use then owns the endpoint, and it stops when that key is revoked or expires.

Returns

200 The webhook endpoint object. The webhook endpoint as it is now.

Errors

Besides the ones every request can get:

422invalid_fieldA field breaks a rule, or a saved header value is sent with a url on another server. error.field is then headers.<name>.

403scope_missingThe key lacks the read scope of an event the endpoint will send.

403feature_not_in_planYou added an event that isn’t on your plan.

404not_foundThere is no webhook endpoint with this ID in your workspace.