Repository files navigation

GitHub webhook events toolset for Node.js

• Usage
• Local development
• API
  • Constructor
  • webhooks.sign()
  • webhooks.verify()
  • webhooks.verifyAndReceive()
  • webhooks.receive()
  • webhooks.on()
  • webhooks.onAny()
  • webhooks.onError()
  • webhooks.removeListener()
  • createNodeMiddleware()
  • Webhook events
  • emitterEventNames
  • validateEventName
• TypeScript
  • EmitterWebhookEventName
  • EmitterWebhookEvent
• License

@octokit/webhooks helps to handle webhook events received from GitHub.

GitHub webhooks can be registered in multiple ways

1. In repository or organization settings ongithub.com.
2. Using the REST API forrepositories ororganizations
3. Bycreating a GitHub App.

Note that while setting a secret is optional on GitHub, it is required to be set in order to use@octokit/webhooks. Content Type must be set toapplication/json,application/x-www-form-urlencoded is not supported.

// install with: npm install@octokit/webhooksimport{Webhooks,createNodeMiddleware}from"@octokit/webhooks";import{createServer}from"node:http";constwebhooks=newWebhooks({secret:"mysecret",});webhooks.onAny(({ id, name, payload})=>{console.log(name,"event received");});createServer(createNodeMiddleware(webhooks)).listen(3000);// can now receive webhook events at /api/github/webhooks

You can receive webhooks on your local machine or even browser usingEventSource andsmee.io.

Go tosmee.io andStart a new channel. Then copy the "Webhook Proxy URL" and

1. enter it in the GitHub App’s "Webhook URL" input
2. pass it to theEventSource constructor, see below

constwebhookProxyUrl="https://smee.io/IrqK0nopGAOc847";// replace with your own Webhook Proxy URLconstsource=newEventSource(webhookProxyUrl);source.onmessage=(event)=>{constwebhookEvent=JSON.parse(event.data);webhooks.verifyAndReceive({id:webhookEvent["x-request-id"],name:webhookEvent["x-github-event"],signature:webhookEvent["x-hub-signature"],payload:JSON.stringify(webhookEvent.body),}).catch(console.error);};

EventSource is a native browser API and can be polyfilled for browsers that don’t support it. In node, you can use theeventsource package: install withnpm install eventsource, thenimport EventSource from "eventsource";)

1. Constructor
2. webhooks.sign()
3. webhooks.verify()
4. webhooks.verifyAndReceive()
5. webhooks.receive()
6. webhooks.on()
7. webhooks.onAny()
8. webhooks.onError()
9. webhooks.removeListener()
10. createNodeMiddleware()
11. createWebMiddleware()
12. Webhook events
13. emitterEventNames
14. validateEventName

newWebhooks({ secret/*, transform */});

Returns thewebhooks API.

webhooks.sign(eventPayload);

Returns asignature string. Throws error ifeventPayload is not passed.

Thesign method can be imported as static method from@octokit/webhooks-methods.

webhooks.verify(eventPayload,signature);

Returnstrue orfalse. Throws error ifeventPayload orsignature not passed.

Theverify method can be imported as static method from@octokit/webhooks-methods.

webhooks.verifyAndReceive({ id, name, payload, signature});

Returns a promise.

Verifies event usingwebhooks.verify(), then handles the event usingwebhooks.receive().

Additionally, if verification fails, rejects the returned promise and emits anerror event.

Example

import{Webhooks}from"@octokit/webhooks";constwebhooks=newWebhooks({secret:"mysecret",});eventHandler.on("error",handleSignatureVerificationError);// put this inside your webhooks route handlereventHandler.verifyAndReceive({id:request.headers["x-github-delivery"],name:request.headers["x-github-event"],payload:request.body,signature:request.headers["x-hub-signature-256"],}).catch(handleErrorsFromHooks);

webhooks.receive({ id, name, payload});

Returns a promise. Runs all handlers set withwebhooks.on() in parallel and waits for them to finish. If one of the handlers rejects or throws an error, thenwebhooks.receive() rejects. The returned error has an.errors property which holds an array of all errors caught from the handlers. If no errors occur,webhooks.receive() resolves without passing any value.

The.receive() method belongs to theevent-handler module which can be usedstandalone.

webhooks.on(eventName,handler);webhooks.on(eventNames,handler);

The.on() method belongs to theevent-handler module which can be usedstandalone.

webhooks.onAny(handler);

The.onAny() method belongs to theevent-handler module which can be usedstandalone.

webhooks.onError(handler);

If a webhook event handler throws an error or returns a promise that rejects, an error event is triggered. You can use this handler for logging or reporting events. The passed error object has a .event property which has all information on the event.

Asynchronouserror event handler are not blocking the.receive() method from completing.

The.onError() method belongs to theevent-handler module which can be usedstandalone.

webhooks.removeListener(eventName,handler);webhooks.removeListener(eventNames,handler);

The.removeListener() method belongs to theevent-handler module which can be usedstandalone.

import{createServer}from"node:http";import{Webhooks,createNodeMiddleware}from"@octokit/webhooks";constwebhooks=newWebhooks({secret:"mysecret",});constmiddleware=createNodeMiddleware(webhooks,{path:"/webhooks"});createServer(async(req,res)=>{// `middleware` returns `false` when `req` is unhandled (beyond `/webhooks`)if(awaitmiddleware(req,res))return;res.writeHead(404);res.end();}).listen(3000);// can now receive user authorization callbacks at POST /webhooks

The middleware returned fromcreateNodeMiddleware can also serve as anExpress.js middleware directly.

import{Webhooks,createWebMiddleware}from"@octokit/webhooks";constwebhooks=newWebhooks({secret:"mysecret",});constmiddleware=createWebMiddleware(webhooks,{path:"/webhooks"});// Example usage in DenoDeno.serve({port:3000},middleware);

The middleware returned fromcreateWebMiddleware can also be used in serverless environments like AWS Lambda, Cloudflare Workers, and Vercel.

See the full list ofevent types with example payloads.

If there are actions for a webhook, events are emitted for both, the webhook name as well as a combination of the webhook name and the action, e.g.installation andinstallation.created.

A read only tuple containing all the possible combinations of the webhook events + actions listed above. This might be useful in GUI and input validation.

import{emitterEventNames}from"@octokit/webhooks";emitterEventNames;// ["check_run", "check_run.completed", ...]

The functionvalidateEventName asserts that the provided event name is a valid event name or event/action combination.It throws an error if the event name is not valid, or '*' or 'error' is passed.

The second parameter is an optional options object that can be used to customize the behavior of the validation. You can setaonUnknownEventName property to"warn" to log a warning instead of throwing an error, and alog property to provide a custom logger object, which should have a"warn" method. You can also setonUnknownEventName to"ignore" to disable logging or throwing an error for unknown event names.

import{validateEventName}from"@octokit/webhooks";validateEventName("push");// no errorvalidateEventName("invalid_event");// throws an errorvalidateEventName("*");// throws an errorvalidateEventName("error");// throws an errorvalidateEventName("invalid_event",{onUnknownEventName:"warn"});// logs a warningvalidateEventName("invalid_event",{onUnknownEventName:false,log:{warn:console.info,// instead of warning we just log it via console.info},});validateEventName("*",{onUnkownEventName:"ignore"});// throws an errorvalidateEventName("invalid_event",{onUnkownEventName:"ignore"});// no error, no warning

The types for the webhook payloads are sourced from@octokit/openapi-webhooks-types,which can be used by themselves.

In addition to these types,@octokit/webhooks exports 2 types specific to itself:

Note that changes to the exported types are not considered breaking changes, as the changes will not impact production code, but only fail locally or during CI at build time.

⚠️ Caution⚠️: Webhooks Types are expected to be used with thestrictNullChecks option enabled in yourtsconfig. If you don't have this option enabled, there's the possibility that you getnever as the inferred type in some use cases. Seeoctokit/webhooks#395 for details.

A union of all possible events and event/action combinations supported by the event emitter, e.g."check_run" | "check_run.completed" | ... many more ... | "workflow_run.requested".

The object that is emitted by@octokit/webhooks as an event; made up of anid,name, andpayload properties.An optional generic parameter can be passed to narrow the type of thename andpayload properties based on event names or event/action combinations, e.g.EmitterWebhookEvent<"check_run" | "code_scanning_alert.fixed">.

MIT