doc: Document webhook

[kdy1]

No description provided.

[claude]

PR Review: Document webhook

Thanks for adding webhook architecture documentation! This is a valuable addition to help users understand how DevBird processes events. Here's my feedback:

✅ Strengths

1. Good structure - The document follows existing patterns with clear sections and hierarchy
2. Frontmatter compliance - Includes required title and description fields
3. Consistent voice - Uses second-person voice ("you") appropriately per CLAUDE.md
4. Practical content - Provides actionable information about webhook events and their effects
5. Minor improvements to index.mdx - Small clarifications improve readability

📝 Content Suggestions

1. Add Prerequisites section (devbird/architecture/webhook.mdx:6)

Per CLAUDE.md standards, consider adding a Prerequisites section at the start to tell users what they need to understand this content:

## Prerequisites

Before reading this guide, ensure you have:

- Completed the [GitHub App installation](/devbird/getting-started/github-app)
- Understanding of GitHub webhooks and events

2. Clarify "Uses GitHub App webhooks or repository webhooks" (devbird/architecture/webhook.mdx:14)

This line is a bit ambiguous. Consider clarifying:

• When does DevBird use GitHub App webhooks vs repository webhooks?
• Is there a preference or recommendation?
• Do users need to configure anything?

Suggested revision:

- Automatically receives events via GitHub App webhooks (recommended)
- Also supports repository-level webhooks for custom configurations

3. Add webhook signature validation details (devbird/architecture/webhook.mdx:15)

The line "Validates webhook signatures using the webhook secret" could be expanded to help users understand security:

• Is this automatic?
• Do users need to configure the webhook secret?
• What happens if validation fails?

4. Consider adding a "Security" section

Given that webhooks involve external requests, consider adding security best practices:

• How DevBird validates webhook authenticity
• What users should know about webhook security
• Whether there are any IP restrictions or other security measures

5. Add "Next steps" section (per existing patterns)

Most getting-started docs include a "Next steps" section. Consider adding:

## Next steps

- [Set up your GitHub workflow](/devbird/getting-started/github-workflow)
- [Configure AI agent](/devbird/getting-started/ai-agent)
- Learn about [reviewing PRs](/devbird/reviewing-prs/index)

6. Minor: Redundant bullet point (devbird/architecture/webhook.mdx:14)

The first bullet "Uses GitHub App webhooks or repository webhooks" is redundant with the section header. Consider removing it or making it more specific.

🔍 Content Accuracy Questions

1. Pull Request Review Comment vs Pull Request Review Submitted (lines 35-40) - Are these actually distinct webhook events in GitHub's API? I believe "Pull Request Review Comment" typically refers to individual review comments, while "Pull Request Review" is for the overall review. Please verify this matches GitHub's webhook event naming.

2. "Undrafts PR when all checks pass" (line 47) - Is this configurable? The parenthetical "(if auto-undraft is enabled)" suggests yes, but this feature isn't documented elsewhere. Consider linking to configuration docs or explaining where this setting is located.

🎨 Style & Formatting

1. Extra blank line (devbird/index.mdx:37) - There's an extra blank line added that doesn't serve a purpose. Consider removing it for consistency.

2. Event naming consistency - Consider using GitHub's official event names (e.g., pull_request, pull_request_review, check_run) in addition to the human-readable descriptions to help developers correlate with GitHub's webhook documentation.

📚 Documentation Strategy Alignment

Per CLAUDE.md:

• ✅ Content is evergreen and unlikely to change frequently
• ✅ No duplication with existing content
• ✅ Follows existing patterns for structure
• ⚠️ Could use code examples (e.g., example webhook payloads) to help users debug
• ⚠️ No internal links yet - consider linking to related getting-started pages

🧪 Testing Recommendations

Per CLAUDE.md standards to "Test all code examples before publishing":

• No code examples in this PR, so N/A
• Consider adding example webhook payloads in the future if users need to debug webhook issues

🎯 Overall Assessment

This is solid foundational documentation that fills a gap in the docs. The content is accurate and well-organized. Addressing the suggestions above would make it even more helpful by:

• Providing more context for users unfamiliar with webhooks
• Clarifying ambiguous statements
• Adding navigation to related content
• Following existing documentation patterns more closely

Recommendation: Approve with minor revisions suggested above. None of the issues are blocking, but addressing them would improve user experience.