Add OAuth Authentication section to Webhooks Overview - #140
Conversation
Documents the OAuth 2.0 client credentials feature for webhook subscriptions: purpose and use cases, OAuth client creation and token validation, subscription association, product limits, and permission requirements. Cross-links the new section from the Behavior page. (DEVECO-358) Co-Authored-By: Claude <noreply@anthropic.com>
|
|
||
| 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 |
There was a problem hiding this comment.
I'm not sure I see the point of adding this information here. It duplicates the authoritative source in the API reference and is just another place that can fall out of sync. I think we could link to the API reference here for the specific details about how the requests work. (Note that Claude can't read that link because it's a SPA, but may have more luck here ).
|
|
||
| #### Permissions and Requirements | ||
|
|
||
| - Managing OAuth clients requires the same permissions as managing webhook subscriptions. |
There was a problem hiding this comment.
Incorrect. It requires admin or owner permissions. In contrast, lower tier users can manage webhook subscriptions belonging to their services.
gaberduty
left a comment
gaberduty
left a comment
There was a problem hiding this comment.
I like the "purpose and use case" bit, but I think we shouldn't duplicate the actual API reference materials here, and should instead just link to them.
2 participants
Summary
docs/webhooks/01-Overview.mdcovering purpose and use cases, OAuth client creation (including token validation at create/update time), associating a client with a webhook subscription viaoauth_client_id, product limits (10 clients per account), and permission/scope requirements. (DEVECO-358)docs/webhooks/02-Behavior.md, matching the pattern used by the Mutual TLS and Signature sections.Test plan
🤖 Generated with Claude Code