DRAFT: Add event-based automations documentation

[malhotra5]

Summary

This PR adds documentation for event-based automations, a new feature that allows automations to be triggered by webhook events (GitHub, custom services) instead of cron schedules.

Based on the capabilities outlined in OpenHands/extensions#156.

Changes

• New page: openhands/usage/automations/event-automations.mdx
• Navigation update: Added to Automations (BETA) group in docs.json

Documentation Coverage

Built-in Events vs Custom Integrations

• Explains the two approaches: built-in GitHub integration (no setup) vs custom webhooks (registration required)
• Comparison table for quick reference

GitHub Event-Based Automation Example

• Auto-review PRs with specific labels
• Respond to @OpenHands mentions
• Available event types reference
• Filter expressions (JMESPath) with common patterns

Linear Custom Integration Walkthrough

Complete step-by-step guide covering:

1. Registering the webhook - Parameters explained (source, signature_header, event_key_expr, webhook_secret)
2. Working with an agent - Conversational setup flow
3. Configuring in Linear - Where to paste the webhook URL and secret
4. Creating the automation - Using the registered webhook source

Reference Tables

• Common services signature headers and event keys (Linear, Stripe, Slack, Twilio)
• Custom webhook parameters

---

This PR was created by an AI assistant (OpenHands) to document upcoming event-based automation features.

@malhotra5 can click here to continue refining the PR

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
all-hands-ai	🟢 Ready	View Preview	Apr 22, 2026, 4:44 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[jpelletier1]

This LGTM!

[all-hands-bot]

Documentation is well-structured and follows existing patterns, but has workflow clarity issues that could confuse users.

[all-hands-bot]

🟡 Suggestion: The event_key_expr parameter needs better explanation. Users need to understand:

1. This JMESPath expression extracts the event type from the webhook payload
2. The extracted value is matched against the on field when creating automations
3. For Linear, the payload has {"type": "Issue", "action": "create", ...} so event_key_expr: "type" extracts "Issue"

Consider adding a concrete example showing the webhook payload → event_key_expr → extracted value → automation on field mapping.

[malhotra5]

Fixed in 958ec67. Added an Accordion component with a concrete explanation:

The event_key_expr is a JMESPath expression that extracts the event type from incoming webhook payloads. This extracted value is what you match against in the automation's on field.

Included a concrete example showing how Linear's payload {"type": "Issue", ...} with event_key_expr: "type" extracts "Issue", which is then matched in the automation's on field.

[all-hands-bot]

Code Review Summary

Taste Rating: 🟡 Acceptable - Documentation follows existing patterns and provides good coverage, but has clarity issues that need addressing.

---

[CRITICAL ISSUES]

• [Lines 88-93] Workflow Contradiction: The note about webhook registration contradicts Step 4's claim that "the agent can create automations end-to-end on your behalf." This creates confusion about what the user vs. the agent is responsible for. Need to clearly separate webhook registration (one-time manual setup) from automation creation (agent-handled).

---

[IMPROVEMENT OPPORTUNITIES]

• [Line 12, 19] Header Capitalization: Inconsistent with style guide. Use Title Case for first and second level headers per DOC_STYLE_GUIDE.md.

• [Line 63] JMESPath Documentation: The JMESPath link is embedded in a code comment, making it hard for users to discover. Add a prose introduction explaining what JMESPath is and linking to the documentation.

• [Lines 120-130] Event Key Expression: The event_key_expr parameter needs better explanation. Users should understand the mapping: webhook payload → event_key_expr → extracted value → automation on field. A concrete example would help.

• [Line 176] Service-Specific Values: The common services table should note that these are examples and may change, recommending users verify with their service's documentation.

• [Line 189] Navigation: Consider adding a link to Automations Overview at the top of "Next Steps" for users who jumped directly to this page.

---

[POSITIVE ASPECTS]

• ✅ Comprehensive Coverage: Good coverage of both GitHub built-in integration and custom webhooks
• ✅ Practical Examples: Excellent filter expression examples with real-world use cases
• ✅ Comparison Table: Clear built-in vs. custom integrations comparison
• ✅ Linear Walkthrough: Detailed step-by-step guide for custom webhook setup
• ✅ Consistent Pattern: Follows the conversational approach established in creating-automations.mdx

---

[RISK ASSESSMENT]

• Overall PR: ⚠️ Risk Assessment: 🟢 LOW

This is documentation-only with no functional changes. The primary risk is user confusion from the workflow contradiction identified above. Once that's clarified, this will be a solid addition to the automation documentation. No breaking changes, no code modifications, no security concerns.

---

VERDICT:
✅ Worth merging after addressing the critical workflow clarity issue

Core content is sound and well-organized. The critical issue (webhook registration workflow confusion) needs resolution before merge to prevent user confusion. Style improvements are nice-to-have but not blockers.

KEY INSIGHT:
The documentation bridges the gap between simple cron-based automations and event-driven workflows effectively, but needs to clarify the boundary between what users do manually (webhook registration) versus what the agent handles (automation creation).

---

Improve this review? If any feedback above seems incorrect or irrelevant to this repository, you can teach the reviewer to do better:

1. Add a .agents/skills/custom-codereview-guide.md file to your branch (or edit it if one already exists) with the /codereview trigger and the context the reviewer is missing (e.g., "Security concerns about X do not apply here because Y"). See the customization docs for the required frontmatter format.
2. Re-request a review - the reviewer reads guidelines from the PR branch, so your changes take effect immediately.
3. When your PR is merged, the guideline file goes through normal code review by repository maintainers.

Resolve with AI? Install the iterate skill in your agent and run /iterate to automatically drive this PR through CI, review, and QA until it's merge-ready.

[malhotra5]

@OpenHands please read the unresolved review comments, address the review and leave a reply under each comment for what fix was made

[openhands-ai]

I'm on it! malhotra5 can track my progress at all-hands.dev

[openhands-ai]

Summary of Work Completed

I've addressed all 7 unresolved review comments on PR #469 and pushed the fixes in commit 958ec67.

Checklist: All Review Comments Addressed ✅

Comment	Issue	Fix Applied	Reply Posted
Line 12	Header capitalization inconsistency	Changed to "Built-In vs. Custom Integrations"	✅
Line 19	Header should be "GitHub Events (Built-In)"	Fixed to match Title Case	✅
Line 63	JMESPath link hard to discover	Added prose explanation before code examples	✅
Lines 88-93	CRITICAL: Workflow contradiction	Rewrote Note to clarify two-phase workflow	✅
Line 130	event_key_expr needs better explanation	Added Accordion with concrete Linear example	✅
Line 176	Signature headers need disclaimer	Added warning to verify with service docs	✅
Line 189	Link to Automations Overview at start	Added intro text for context	✅

Changes Are Concise ✅

• All 7 changes directly address the review feedback
• No extraneous modifications were made
• The commit adds 23 lines and removes 6 lines—focused edits only
• Each fix is minimal and targeted to the specific issue raised

Actions Completed

1. ✅ Read all unresolved review comments via GitHub API
2. ✅ Made all requested fixes to openhands/usage/automations/event-automations.mdx
3. ✅ Committed changes with descriptive message
4. ✅ Pushed to the docs/event-based-automations branch
5. ✅ Replied to each review comment explaining the fix with commit reference

PR Link: #469

[all-hands-bot]

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW

This is documentation for a beta feature with no code changes. The documentation is technically accurate, well-structured, and follows Mintlify conventions. Previous review issues regarding workflow clarity, title case consistency, and disclaimers have been resolved.

VERDICT:
✅ Worth merging (for draft): Documentation is comprehensive and accurate. Minor enhancements suggested to improve first-time user experience.

KEY INSIGHT:
The document successfully bridges the gap between built-in GitHub integration and custom webhook setup, with the Linear walkthrough providing a concrete end-to-end example.

[DevinVinson]

Looks great! Thank you for the detailed docs while still in Beta.