How to Receive GitHub App Webhooks

A GitHub App delivers events to one webhook URL; verify the shared secret, then route on the X-GitHub-Event header.

Configure a webhook URL and secret in the App settings. Every delivery carries X-GitHub-Event (the event name) and X-Hub-Signature-256, which you must verify before acting.

Steps

• Set the webhook URL and a strong secret in the App settings.
• Subscribe the App to the events you need (pull_request, push, and so on).
• Verify X-Hub-Signature-256, then switch on X-GitHub-Event.

Router

function route(headers, payload) {
  const event = headers['x-github-event'];
  switch (event) {
    case 'pull_request':
      return onPullRequest(payload);
    case 'push':
      return onPush(payload);
    case 'installation':
      return onInstallation(payload);
    default:
      return { status: 204 };
  }
}

Gotchas

• GitHub sends a ping event on setup; return 2xx so the hook shows as healthy.
• App tokens are short-lived; exchange the installation id for a token per delivery.

Related guides