---
id: webhooks-update
slug: /apis/webhooks/update
title: 'Update a Subscription'
description: 'Change a webhook subscription with POST ~/api/webhook/:id.'
sidebar_label: 'Update'
sidebar_position: 6
tags: ['api', 'webhooks', 'update']
---

## Request

```text
POST ~/api/webhook/:id
```

`:id` is the **server-assigned UUID** returned by
[create](/apis/webhooks/create#response) — not your `webhookId`.

:::note It is a `POST`, not a `PUT` or `PATCH`
These APIs accept only `GET` and `POST`. Sending `PUT` or `PATCH` returns `405`. See
[errors](/apis/conventions/errors).
:::

### Payload

```json
{
  "url": "https://newurl.com",
  "enabled": false,
  "description": "Updated description of the webhook subscription",
  "eventTypes": []
}
```

The same fields accepted by [create](/apis/webhooks/create#payload) apply here, including
`authorizationHeader` and `secret`.

```bash title="Disabling a subscription"
curl -X POST "https://{host}/{instance}/api/webhook/336d997f-d9fa-4612-80e8-9f41a4b41352" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "enabled": false }'
```

:::warning Send the whole subscription, not just the change
Update replaces the subscription's configuration rather than merging into it. In particular,
sending a payload without `eventTypes` can leave the subscription with no event rules at all —
enabled, healthy-looking, and silent.

The safe pattern is read-modify-write: [`GET ~/api/webhook/:id`](/apis/webhooks/query#retrieve-one-subscription),
change the fields you want, and post the complete object back.

Note the corollary for the write-only fields: because `authorizationHeader` and `secret` are
never returned by a read, a naive read-modify-write **clears them**. Re-supply them from your
own copy on every update.
:::

## Response

The full updated subscription, in the same shape as the
[create response](/apis/webhooks/create#response):

```json title="200 OK"
{
  "id": "336d997f-d9fa-4612-80e8-9f41a4b41352",
  "webhookId": "Webhook identifier",
  "url": "https://newurl.com",
  "description": "Updated description of the webhook subscription",
  "enabled": false,
  "eventTypes": [],
  "lastResponseAt": "0001-01-01T00:00:00Z",
  "retryCount": 0,
  "createdAt": "2018-09-27T20:28:41.3829451Z",
  "updatedAt": "2018-09-27T20:28:41.3829451Z",
  "createdBy": "Member:20"
}
```

`updatedAt` advances; `createdAt` and `createdBy` do not.

## Re-Enabling a Disabled Subscription

A subscription taken out of service by repeated delivery failures is re-enabled the same way —
`POST` with `"enabled": true`.

Fix the receiving end first. Check [delivery status](/apis/webhooks/status) to see what your
endpoint actually returned, correct that, and only then re-enable. Re-enabling against a still-
broken endpoint simply burns the retry budget again.

## Related Topics

- [Create a subscription](/apis/webhooks/create) — the full field reference
- [Query subscriptions](/apis/webhooks/query) — read before you write
- [Delivery status](/apis/webhooks/status)
- [Delete a subscription](/apis/webhooks/delete)