# Change a webhook endpoint

`PATCH /v1/webhooks/{id}`

Changes the fields you send and keeps the others.

Needs `webhooks:write`.

## 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): One 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.

## Example

```sh
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
  }'
```

Response 200:

```json
{
  "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"
}
```

## Returns

200. The webhook endpoint as it is now.

## Errors

Besides the ones every request can get (https://docs.soosh.io/reference/api/errors/):

- 422 `invalid_field`: A field breaks a rule, or a saved header value is sent with a `url` on another server. `error.field` is then `headers.<name>`.
- 403 `scope_missing`: The key lacks the read scope of an event the endpoint will send.
- 403 `feature_not_in_plan`: You added an event that isn't on your plan.
- 404 `not_found`: There is no webhook endpoint with this ID in your workspace.