> Documentation index for AI agents: https://docs.pagerduty.com/llms.txt

# Update a webhook subscription

`PUT https://api.pagerduty.com/webhook_subscriptions/{id}`

Updates an existing webhook subscription.

Only the fields being updated need to be included on the request.  This operation does not
support updating the `delivery_method` of the webhook subscription.

Scoped OAuth requires: `webhook_subscriptions.write`

## Authorization

- **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=<API_KEY>`

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes | The ID of the resource. |

## Header parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. |

## Request body (`application/json`)

| Field | Type | Required | Description |
|---|---|---|---|
| `webhook_subscription` | object |  |  |
| `webhook_subscription.description` | string |  | A short description of the webhook subscription. |
| `webhook_subscription.events` | array of string |  | The set of outbound event types the subscription will receive. Min items: 1. Items must be unique. |
| `webhook_subscription.filter` | object |  |  |
| `webhook_subscription.filter.id` | string |  | The id of the object being used as the filter. This field is required for all filter types except account_reference. |
| `webhook_subscription.filter.type` | string |  | The type of object being used as the filter. One of: `account_reference`, `service_reference`, `team_reference`. |
| `webhook_subscription.active` | boolean |  | If true, a webhook will be sent. True is the default state. If false, a webhook will not be sent. |
| `webhook_subscription.oauth_client_id` | string \| null |  | The ID of the OAuth client to use for authenticating webhook requests. Optional field. |

Example: Update Subscribed Events

```json
{
  "webhook_subscription": {
    "events": [
      "incident.acknowledged",
      "incident.annotated",
      "incident.delegated",
      "incident.escalated",
      "incident.priority_updated",
      "incident.reassigned",
      "incident.reopened",
      "incident.resolved",
      "incident.responder.added",
      "incident.responder.replied",
      "incident.triggered",
      "incident.unacknowledged"
    ]
  }
}
```

## Response 200

The updated webhook subscription.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `webhook_subscription` | object | yes |  |
| `webhook_subscription.id` | string |  | Read-only. |
| `webhook_subscription.type` | string | yes | The type indicating the schema of the object. One of: `webhook_subscription`. Default: `webhook_subscription`. |
| `webhook_subscription.active` | boolean |  | Determines whether this subscription will produce webhook events. Default: `true`. |
| `webhook_subscription.delivery_method` | object | yes |  |
| `webhook_subscription.delivery_method.id` | string |  | Read-only. |
| `webhook_subscription.delivery_method.secret` | string \| null |  | The secret used to sign webhook payloads. Only provided on the initial create response. Read-only. |
| `webhook_subscription.delivery_method.temporarily_disabled` | boolean |  | Whether or not this webhook subscription is temporarily disabled. Becomes `true` if the delivery method URL is repeatedly rejected by the server. |
| `webhook_subscription.delivery_method.type` | string | yes | Indicates the type of the delivery method. One of: `http_delivery_method`. Default: `http_delivery_method`. |
| `webhook_subscription.delivery_method.url` | string (url) | yes | The destination URL for webhook delivery. |
| `webhook_subscription.delivery_method.custom_headers` | array of object |  | Optional headers to be set on this webhook subscription when sent. The header values are redacted in GET requests, but are not redacted on the webhook when delivered to the webhook's endpoint. |
| `webhook_subscription.delivery_method.custom_headers[].name` | string |  | The header name. |
| `webhook_subscription.delivery_method.custom_headers[].value` | string |  | The header value. |
| `webhook_subscription.description` | string |  | A short description of the webhook subscription. |
| `webhook_subscription.events` | array of string | yes | The set of outbound event types the webhook will receive. Min items: 1. Items must be unique. |
| `webhook_subscription.filter` | object | yes |  |
| `webhook_subscription.filter.id` | string |  | The id of the object being used as the filter. This field is required for all filter types except account_reference. |
| `webhook_subscription.filter.type` | string | yes | The type of object being used as the filter. One of: `account_reference`, `service_reference`, `team_reference`. |
| `webhook_subscription.oauth_client` | object |  | OAuth client details. This field is populated in responses when oauth_client_id is set. Read-only. |
| `webhook_subscription.oauth_client.id` | string | yes | The ID of the OAuth client. |
| `webhook_subscription.oauth_client.type` | string | yes | The type of object being referenced. One of: `oauth_client_reference`. Default: `oauth_client_reference`. |
| `webhook_subscription.oauth_client.summary` | string |  | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. Read-only. |

Example: Example

```json
{
  "webhook_subscription": {
    "delivery_method": {
      "id": "PF9KMXH",
      "secret": null,
      "temporarily_disabled": false,
      "type": "http_delivery_method",
      "url": "https://example.com/receive_a_pagerduty_webhook",
      "custom_headers": [
        {
          "name": "your-header-name",
          "value": "-- redacted --"
        }
      ]
    },
    "description": "Sends PagerDuty v3 webhook events somewhere interesting.",
    "events": [
      "incident.acknowledged",
      "incident.annotated",
      "incident.delegated",
      "incident.escalated",
      "incident.priority_updated",
      "incident.reassigned",
      "incident.reopened",
      "incident.resolved",
      "incident.responder.added",
      "incident.responder.replied",
      "incident.triggered",
      "incident.unacknowledged"
    ],
    "filter": {
      "id": "P393ZNQ",
      "type": "service_reference"
    },
    "oauth_client": {
      "id": "AGLRZQ2PGR5B7EQ52DTT4ZJERY",
      "type": "oauth_client_reference",
      "summary": "PagerDuty Webhook Integration"
    },
    "id": "PY1OL64",
    "type": "webhook_subscription",
    "active": true
  }
}
```

## Response 400

Caller provided invalid arguments. Please review the response for error
details. Retrying with the same arguments will *not* work.

## Response 401

Caller did not supply credentials or did not provide the correct
credentials.

If you are using an API key, it may be invalid or your Authorization header may be malformed.

## Response 403

Caller is not authorized to view the requested resource.

While your authentication is valid, the authenticated user or token does not have permission to perform this action.

## Response 404

The requested resource was not found.

## Developer Agreement

Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement).