Add OAuth Authentication section to Webhooks Overview

docs/webhooks/01-Overview.md

@@ -80,6 +80,71 @@ The `filter` of a webhook subscription determines which events will match and pr
 
 In the case of incident events, the different filter types will only produce webhooks for the incidents that are associated with the filter object. For example: a webhook subscription with a service filter would produce webhooks for all incidents belonging to the specified service.
 
+### OAuth Authentication
+
+PagerDuty can authenticate webhook deliveries to your endpoint using the [OAuth 2.0 client credentials flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4). When a webhook subscription is associated with an _OAuth client_, PagerDuty obtains an access token from your authorization server and includes it as a bearer token in the `Authorization` header of each webhook request.
+
+#### Purpose and Use Cases
+
+OAuth authentication is useful when your webhook destination requires token-based authentication rather than static credentials. Common use cases include:
+
+- Delivering webhooks to platforms that require OAuth for inbound requests, such as ServiceNow
+- Enterprise environments with security policies that prohibit static secrets (such as basic auth credentials in URLs or fixed custom headers)
+- Endpoints that need the ability to revoke or rotate credentials centrally on their own authorization server
+
+Compared to static authentication methods, OAuth provides automatic token refresh and retry behavior: if a delivery receives a `401 Unauthorized` response, PagerDuty refreshes the token and immediately retries. See [OAuth Authentication Retries](../../docs/webhooks/02-Behavior.md#oauth-authentication-retries) for complete retry behavior.
+
+#### Creating an OAuth Client
+
+Create an OAuth client using the OAuth Clients API (`POST /webhook_subscriptions/oauth_clients`) or from the Webhooks page in the PagerDuty web app. An OAuth client consists of:
+
+| Field           | Description                                                                                  |
+| --------------- | -------------------------------------------------------------------------------------------- |
+| `name`          | A friendly name for the OAuth client.                                                        |
+| `client_id`     | The client ID issued by your OAuth authorization server.                                     |
+| `client_secret` | The client secret issued by your OAuth authorization server. Redacted in API responses.       |
+| `token_url`     | The token endpoint on your authorization server that PagerDuty will request access tokens from. |
+| `grant_type`    | Must be `client_credentials`.                                                                |
+| `scope`         | Optional. Scopes to request from your authorization server, if it requires them.             |
+
+When an OAuth client is created or updated, PagerDuty validates the configuration by requesting an access token from the `token_url`. If a token cannot be obtained, the create or update request fails. Ensure your authorization server is reachable from the public internet and that the credentials are valid before creating the client.
+
+#### Associating an OAuth Client with a Webhook Subscription
+
+Reference the OAuth client by ID when creating or updating a webhook subscription:
+
+```json
+{
+  "webhook_subscription": {
+    "delivery_method": {
+      "type": "http_delivery_method",
+      "url": "https://example.com/receive_a_pagerduty_webhook"
+    },
+    "description": "Sends PagerDuty v3 webhook events with OAuth authentication.",
+    "events": ["incident.triggered", "incident.resolved"],
+    "filter": {
+      "id": "P393ZNQ",
+      "type": "service_reference"
+    },
+    "oauth_client_id": "AGMEB7F7YJYELCPG4Y5YWMYGXE",
+    "type": "webhook_subscription"
+  }
+}
+```
+
+A single OAuth client may be used by multiple webhook subscriptions. Deleting an OAuth client removes the association from any webhook subscriptions using it.
+
+#### Product Limits
+
+Each account may have a maximum of **10 OAuth clients**. Requests to create additional clients beyond this limit return a `400` error with error code `2019`.
+
+#### Permissions and Requirements
+
+- Managing OAuth clients requires the same permissions as managing webhook subscriptions.
+- For [Scoped OAuth](https://developer.pagerduty.com/docs/oauth-functionality) API access, listing and reading OAuth clients requires the `webhook_subscriptions.read` scope; creating, updating, and deleting them requires the `webhook_subscriptions.write` scope.
+- Only the `client_credentials` grant type is supported.
+- Your authorization server must implement the token endpoint per [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749). If the token response omits `token_type`, PagerDuty assumes `Bearer`.
+
 ### More Details
 
 Please see the full [Webhook Subscriptions API Reference](https://developer.pagerduty.com/api-reference/b3A6MjkyNDc4NA-create-a-webhook-subscription) for more details.

docs/webhooks/02-Behavior.md

@@ -85,6 +85,9 @@ We send a client TLS certificate with webhooks on request. You can use this to v
 ### OAuth Authentication
 
 PagerDuty supports OAuth 2.0 client credentials flow for webhook authentication. You can create OAuth clients and associate them with webhook subscriptions to automatically include OAuth bearer tokens in webhook requests.
+<br/>
+
+[Learn how to set up OAuth authentication for webhooks](../../docs/webhooks/01-Overview.md#oauth-authentication)
 
 ### Webhook Signature Validation