Join us for office hours !

Receiving webhooks

GitHub webhooks are fired for almost every significant action that users take on GitHub, whether it's pushes to code, opening or closing issues, opening or merging pull requests, or commenting on a discussion.

Many apps will spend their entire day responding to these actions. app.on will listen for any GitHub webhook events:

module.exports = app => {
  app.on('push', async context => {
    // Code was pushed to the repo, what should we do with it?
    app.log(context)
  })
}

The app can listen to any of the GitHub webhook events. The context object includes everything about the event that was triggered, and context.payload has the payload delivered by GitHub.

Most events also include an "action". For example, the issues event has actions of assigned, unassigned, labeled, unlabeled, opened, edited, milestoned, demilestoned, closed, and reopened. Often, your app will only care about one type of action, so you can append it to the event name with a .:

module.exports = app => {
  app.on('issues.opened', async context => {
    // An issue was just opened.
  })
}

Sometimes you want to handle multiple webhook events the same way. app.on can listen to a list of events and run the same callback:

module.exports = app => {
  app.on(['issues.opened', 'issues.edited'], async context => {
    // An issue was opened or edited, what should we do with it?
    app.log(context)
  })
}

You can also use the wildcard event (*) to listen for any event that your app is subscribed to:

module.exports = app => {
  app.on(`*`, async context => {
    context.log({ event: context.event, action: context.payload.action })
  })
}

Explore the GitHub webhook documentation to see what events are available to use in your app.

Found a mistake or want to help improve this documentation? Suggest changes on GitHub

Get occasional updates on new apps & features.

Star

with by @bkeepers

Code licensed ISC Docs licensed CC-BY-4.0