Skip to main content

​
Subscribed events

MergeWatch subscribes to the following GitHub webhook events:
Only the events and actions listed above trigger processing. All other webhook deliveries are acknowledged but ignored.
MergeWatch recognizes three mention commands: @mergewatch review (full review), @mergewatch summary (summary only), and @mergewatch with any other text (conversational response — the LLM replies directly to the user’s comment using the PR diff and previous review findings as context; no review pipeline runs). All mentions are case-insensitive.

​
Webhook security

All incoming webhooks are signed by GitHub using HMAC-SHA256. The WebhookHandler Lambda validates the X-Hub-Signature-256 header against the stored webhook secret before processing any event.
Invalid signatures are rejected with a 401 Unauthorized response. If you see 401 errors in your GitHub App webhook delivery log, verify that the webhook secret in AWS SSM Parameter Store matches the value in your GitHub App settings.

​
Retry behavior

GitHub automatically retries webhook deliveries that receive non-2xx responses. To prevent duplicate processing, MergeWatch always returns a 200 OK response to GitHub, even when an internal error occurs. Errors are captured and handled asynchronously:
  • Failed reviews are logged to CloudWatch.
  • The original webhook payload is preserved for debugging.
  • No duplicate review is triggered by a GitHub retry.

​
Payload size

GitHub webhook payloads do not include the full diff of a pull request. After receiving a pull_request webhook event, MergeWatch fetches the diff separately via the GitHub REST API using the installation access token. This ensures MergeWatch always works with the complete diff regardless of payload size limits.

​
Next steps

Permissions reference

Review the GitHub permissions MergeWatch requests and why each is needed.

Architecture

Understand how webhooks flow through the MergeWatch deployment stack.