Webhooks

ReleaseRay uses GitHub webhooks to automatically capture pull requests and issues as they're merged and closed. This guide explains how webhooks work, what data we collect, and how to troubleshoot common issues.

Overview

Webhooks are automatic. When you install the ReleaseRay GitHub App, we automatically configure webhooks for you. You don't need to manually set up webhook URLs or manage secrets.

What Happens

  1. You merge a PR or close an issue in GitHub
  2. GitHub sends a webhook to ReleaseRay within seconds
  3. We process the data and store PR/issue metadata
  4. You generate release notes that include all merged PRs

This happens automatically in the background. No configuration needed.

How It Works

Installation Process

When you install the ReleaseRay GitHub App:

  1. GitHub creates webhooks for your selected repositories
  2. ReleaseRay receives events when PRs are merged, issues are closed, etc.
  3. Webhook secret is managed automatically by GitHub (you never see it)
  4. Events are verified using HMAC SHA-256 signatures

What Events We Subscribe To

ReleaseRay listens for these GitHub events:

  • ✅ Pull Request (pull_request)
    • Opened, edited, closed, merged
    • We capture: title, body, labels, author, merge date, linked issues
  • ✅ Issues (issues)
    • Opened, edited, closed
    • We capture: title, body, labels, author, close date
  • ✅ Push (push)
    • When commits are pushed (for tag detection)
    • We capture: tags, commit messages

We do NOT subscribe to:

  • ❌ Code content events (we never see your source code)
  • ❌ Comments (we don't need PR/issue comments)
  • ❌ Reviews (PR reviews aren't needed for release notes)

Webhook Security

HMAC Signature Verification

Every webhook GitHub sends includes a signature:

X-Hub-Signature-256: sha256=abc123...

ReleaseRay verifies this signature before processing any webhook. This ensures:

  • ✅ Webhooks came from GitHub (not a malicious actor)
  • ✅ Webhooks weren't tampered with in transit
  • ✅ Your data is protected

If signature verification fails, the webhook is rejected with a 401 Unauthorized response.

IP Whitelisting (Optional)

GitHub webhooks come from specific IP ranges. If you have a corporate firewall, you may need to whitelist:

192.30.252.0/22
185.199.108.0/22
140.82.112.0/20
143.55.64.0/20

See GitHub's IP ranges for the current list.

Data Collection

What We Capture

From Pull Requests:

  • PR number (e.g., #245)
  • Title (e.g., "Add OAuth2 PKCE support")
  • Description/body (markdown text)
  • Labels (e.g., feature, bug, breaking)
  • Author (GitHub username)
  • Merge date and time
  • Linked issues (detected from "closes #123" in description)
  • State (open, closed, merged)

From Issues:

  • Issue number (e.g., #123)
  • Title
  • Description/body
  • Labels
  • Author
  • Close date (if closed)
  • State (open, closed)

From Push Events:

  • Git tags (e.g., v1.2.0)
  • Tag dates
  • Commit SHAs (for linking)

What We DON'T Capture

  • ❌ Source code (we have no access to repository contents)
  • ❌ File diffs or code changes
  • ❌ PR/issue comments
  • ❌ Review comments or approval status
  • ❌ Commit contents (only metadata)

Webhook Processing

Processing Pipeline

GitHub Event → ReleaseRay API → Background Queue → Database
  1. Webhook arrives at /api/webhooks/github
  2. Signature verified (rejects if invalid)
  3. Event enqueued in Redis (BullMQ)
  4. Background worker processes the event
  5. Data stored in PostgreSQL

Processing Time

  • Webhook receipt: Instant (< 100ms)
  • Background processing: 1-5 seconds
  • Data available: Within 10 seconds of merge

You can generate release notes immediately after merging a PR. The data will be there.

Rate Limiting

GitHub's Limits

GitHub rate limits webhooks to prevent abuse:

  • 5000 events per hour per repository
  • 50 events per minute per repository

If you exceed these limits, GitHub will queue events and deliver them later.

ReleaseRay's Limits

We rate limit webhook ingestion:

  • 100 webhooks per minute per organization
  • 1000 webhooks per hour per organization

This prevents runaway automation from overwhelming our system.

Webhook Failures

Why Webhooks Fail

Common reasons webhooks might fail:

  1. Signature verification failed

    • GitHub secret doesn't match
    • Webhook was tampered with
    • Clock skew between GitHub and ReleaseRay

  2. Rate limit exceeded

    • Too many events in a short time
    • GitHub or ReleaseRay rate limits hit

  3. Service downtime

    • ReleaseRay API temporarily unavailable
    • Scheduled maintenance

  4. Invalid payload

    • Malformed JSON
    • Missing required fields

Webhook Retries

If a webhook fails, GitHub automatically retries:

  • Retry 1: After 1 minute
  • Retry 2: After 5 minutes
  • Retry 3: After 15 minutes
  • Retry 4: After 1 hour
  • Retry 5: After 6 hours

After 5 retries, GitHub gives up and marks the webhook as failed.

Monitoring Webhooks

GitHub's Webhook Dashboard

Check webhook delivery status:

  1. Go to your GitHub organization settings
  2. Navigate to Installed GitHub Apps
  3. Click Configure next to ReleaseRay
  4. Click Advanced tab
  5. View Recent Deliveries

You'll see:

  • ✅ Successful deliveries (HTTP 200)
  • ⚠️ Failed deliveries (HTTP 4xx/5xx)
  • 🔄 Pending retries

ReleaseRay Dashboard

Check ingestion status:

  1. Go to ReleaseRay dashboard
  2. Navigate to Settings → Webhooks
  3. View recent webhook activity

You'll see:

  • Last webhook received
  • Total webhooks processed
  • Any errors or failures

Troubleshooting

"No PRs showing up"

Check:

  1. ✅ GitHub App is installed on the repository
  2. ✅ Repository is selected in ReleaseRay
  3. ✅ PRs are actually merged (not just closed)
  4. ✅ Webhook deliveries are succeeding (check GitHub dashboard)

Solution:

  • Wait 10 seconds after merging
  • Check webhook delivery status in GitHub
  • Contact support if webhooks are failing

"Old PRs are missing"

Explanation: Webhooks only capture events that happen AFTER installation.

Solution:

  • Use the "Backfill" feature in ReleaseRay
  • Go to Settings → Repositories → Select repo → Click "Backfill Data"
  • We'll fetch historical PRs via GitHub API

"Webhook signature verification failed"

Causes:

  • GitHub App was reinstalled (new secret generated)
  • Man-in-the-middle attack (rare)
  • Clock skew (very rare)

Solution:

  1. Reinstall the GitHub App
  2. Check status.releaseray.com for incidents
  3. Contact support if issue persists

"Rate limit exceeded"

Causes:

  • Merging >100 PRs per minute
  • Automation scripts creating PRs too fast

Solution:

  • Slow down PR creation/merging
  • Webhooks will queue and process when rate limit resets
  • Data won't be lost, just delayed

Webhook Payload Examples

Pull Request Merged

{
  "action": "closed",
  "pull_request": {
    "number": 245,
    "title": "Add OAuth2 PKCE support",
    "body": "Implements PKCE flow for enhanced security. Closes #234",
    "state": "closed",
    "merged": true,
    "merged_at": "2025-11-03T14:32:00Z",
    "user": {
      "login": "johndoe"
    },
    "labels": [{ "name": "feature" }, { "name": "security" }]
  },
  "repository": {
    "full_name": "acme/myapp"
  }
}

Issue Closed

{
  "action": "closed",
  "issue": {
    "number": 234,
    "title": "Add SSO support for enterprise customers",
    "body": "We need OAuth2 PKCE for enterprise SSO...",
    "state": "closed",
    "closed_at": "2025-11-03T14:32:00Z",
    "user": {
      "login": "janedoe"
    },
    "labels": [{ "name": "enhancement" }, { "name": "enterprise" }]
  },
  "repository": {
    "full_name": "acme/myapp"
  }
}

Best Practices

PR Title Guidelines

Webhook data is only as good as your PR metadata. Write clear titles:

❌ Bad:

  • "fix stuff"
  • "update code"
  • "changes"

✅ Good:

  • "Fix race condition in webhook processor causing duplicate events"
  • "Add OAuth2 PKCE support for enhanced security"
  • "Update Stripe integration to latest API version"

ReleaseRay uses PR titles as the first line of your release notes. Make them count.

Use Labels

Labels help ReleaseRay categorize changes:

  • type: feature → Features section
  • type: bug → Bug Fixes section
  • type: breaking → Breaking Changes section
  • area: auth → Group by area
  • priority: high → Prioritize in notes

Link Issues

Use "closes #123" in PR descriptions to link PRs to issues:

## Description

This PR adds OAuth2 PKCE support.

Closes #234
Fixes #235
Resolves #236

ReleaseRay will pull context from linked issues for richer release notes.

Webhook API Reference

Endpoint

POST https://app.releaseray.com/api/webhooks/github

Headers

X-Hub-Signature-256: sha256=<HMAC>
X-GitHub-Event: pull_request
X-GitHub-Delivery: <UUID>
Content-Type: application/json

Response Codes

  • 200 OK: Webhook processed successfully
  • 202 Accepted: Webhook queued for processing
  • 400 Bad Request: Invalid payload
  • 401 Unauthorized: Signature verification failed
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Processing error (will retry)

Advanced: Manual Webhook Testing

Send Test Webhook

You can manually trigger a webhook from GitHub:

  1. Go to GitHub App settings → Advanced tab
  2. Find a recent delivery
  3. Click Redeliver

This is useful for testing webhook processing without creating real PRs.

Local Testing with ngrok

For development:

# Start ReleaseRay locally
pnpm dev

# In another terminal, start ngrok
ngrok http 3001

# Update GitHub App webhook URL to ngrok URL
# Example: https://abc123.ngrok.io/api/webhooks/github

See SETUP_GUIDE.md for detailed local development setup.

Compliance & Privacy

Data Retention

Webhook data is retained according to our Privacy Policy:

  • Active repositories: PRs/issues retained for 12 months after last sync
  • Inactive repositories: Data deleted 30 days after app uninstall
  • Released notes: Retained indefinitely (you can delete)

GDPR Compliance

Webhook data is processed under legitimate interest (GDPR Article 6(1)(f)):

  • We need PR/issue data to generate release notes (core service)
  • Data is limited to what's necessary
  • You can delete your data anytime

Data Processing Addendum

For enterprise customers, we offer a Data Processing Addendum (DPA) covering webhook data handling.

Contact sales@releaseray.com for details.

FAQ

Do I need to configure webhooks manually?

No. Webhooks are automatically configured when you install the GitHub App.

Can I disable webhooks for specific repositories?

Yes. Unselect repositories in your GitHub App installation settings. Webhooks will stop immediately.

What happens if I reinstall the GitHub App?

Webhooks are recreated automatically. Historical data is preserved (unless you explicitly delete it).

Can I see webhook payloads?

Yes. Check Recent Deliveries in GitHub App settings → Advanced tab. You can view full payloads and responses.

Do webhooks work with GitHub Enterprise?

Yes. ReleaseRay supports GitHub Enterprise Server 3.0+. Contact support for setup guidance.

Support

Need Help?

Questions about webhooks? We're here to help!

Report Webhook Issues

If webhooks aren't working:

  1. Check GitHub's Recent Deliveries for errors
  2. Check our status page for incidents
  3. Email support with:
    • Repository name
    • Approximate time of issue
    • Screenshot of failed delivery (if available)

We'll investigate and resolve within 24 hours.

Related Documentation

We value your privacy

We use cookies to enhance your experience. Essential cookies are required for the site to function. You can choose to accept all cookies or manage your preferences.