Webhook Setup Troubleshooting

Webhooks are how Koalr receives real-time events from GitHub. If webhooks are not working, Koalr falls back to periodic polling, which means your dashboards will be delayed by up to 5 minutes instead of updating in near real-time. This page covers how to verify your webhook setup and resolve common issues.

Verifying the GitHub webhook is registered

From Koalr

1. Go to Settings → Integrations → GitHub.
2. Look for the Webhook row in the integration details section.
3. The status should show Active with a green indicator.
4. Click View webhook to see the full webhook configuration, including the endpoint URL and which event types are subscribed.

If the status shows Failed or Not registered, see the troubleshooting steps below.

From GitHub

You can also verify the webhook directly in your GitHub organization settings:

1. Go to your GitHub organization page.
2. Click Settings → Webhooks.
3. Look for a webhook with the URL https://api.koalr.com/webhooks/github.
4. The webhook should show a green checkmark indicating recent successful deliveries.
5. Click the webhook to see its delivery history. Recent deliveries should show HTTP 200 responses from Koalr.

If the webhook is not listed in GitHub, it was never registered or was deleted. Use Koalr's Re-register webhook button (see below) to create it again.

Common issues and resolutions

Webhook secret mismatch

Symptom: The webhook is visible in GitHub and shows deliveries, but Koalr's integration page shows Failed or data is not updating.

Cause: The webhook secret stored in Koalr does not match the secret registered with GitHub. This can happen if the GitHub integration was reconnected without updating the webhook, or if the webhook was manually edited in GitHub.

Resolution: Disconnect and reconnect the GitHub integration in Koalr. The reconnection flow generates a new webhook secret, deletes the old webhook, and registers a new one with the correct secret.

Org-level vs repo-level webhooks

Symptom: Some repositories receive updates but others do not.

Cause: Koalr registers an organization-level webhook, which covers all repositories in the organization. If you see updates for some repositories but not others, the missing repositories may have been added to the GitHub organization after the webhook was registered, or they may belong to a different GitHub organization.

Resolution: Verify that all repositories are in the same GitHub organization as the one connected to Koalr. If repositories span multiple GitHub organizations, you must connect each organization separately from Settings → Integrations → GitHub.

Firewall blocking Railway IP addresses

Symptom: The webhook is registered in GitHub and deliveries appear to succeed (GitHub shows HTTP 200), but events are not appearing in Koalr.

Cause: This should not be an issue for GitHub webhooks (GitHub sends to Koalr, not the other way around), but it can occasionally affect outbound connections from Koalr to GitHub when Koalr verifies the webhook during registration.

Resolution: Koalr's API runs on Railway. If your organization uses an IP allowlist for GitHub API access, ensure Railway's IP ranges are allowed. Contact Railway's documentation for their current egress IP ranges.

Insufficient organization admin permissions

Symptom: The GitHub connection completes but the webhook status shows Failed to register.

Cause: The GitHub user who authorized the OAuth connection does not have organization admin access. Registering organization-level webhooks requires admin access in the GitHub organization.

Resolution: Have a GitHub organization owner reconnect the integration, or grant the connecting user organization admin access first. See GitHub Permissions for the full permissions breakdown.

Manually re-triggering webhook registration

If the webhook registration failed or the webhook was accidentally deleted from GitHub, you can re-register it from Koalr without disconnecting and reconnecting the full integration:

1. Go to Settings → Integrations → GitHub.
2. Click the Re-register webhook button (visible when webhook status is Failed or Not registered).
3. Koalr will attempt to create a new organization-level webhook with a fresh secret.
4. The status will update within 30 seconds.

If re-registration fails, check the error message displayed below the button. The most common cause is insufficient GitHub permissions, which requires reconnecting the integration with an org admin account.

Testing webhook delivery

To verify that GitHub is successfully delivering events to Koalr:

1. In GitHub, go to Organization Settings → Webhooks → [Koalr webhook].
2. Click Recent Deliveries.
3. Find a recent delivery and click it.
4. Check the Response tab — it should show HTTP 200.
5. You can also click Redeliver to resend any previous event if you want to confirm Koalr processes it correctly.