UNPKG

48.8 kBMarkdownView Raw
1# @octokit/webhooks
2
3> GitHub webhook events toolset for Node.js
4
5[![@latest](https://img.shields.io/npm/v/@octokit/webhooks.svg)](https://www.npmjs.com/package/@octokit/webhooks)
6[![Test](https://github.com/octokit/webhooks.js/workflows/Test/badge.svg)](https://github.com/octokit/webhooks.js/actions?query=workflow)
7
8<!-- toc -->
9
10- [Usage](#usage)
11- [Local development](#local-development)
12- [API](#api)
13 - [Constructor](#constructor)
14 - [webhooks.sign()](#webhookssign)
15 - [webhooks.verify()](#webhooksverify)
16 - [webhooks.verifyAndReceive()](#webhooksverifyandreceive)
17 - [webhooks.receive()](#webhooksreceive)
18 - [webhooks.on()](#webhookson)
19 - [webhooks.onAny()](#webhooksonany)
20 - [webhooks.onError()](#webhooksonerror)
21 - [webhooks.removeListener()](#webhooksremovelistener)
22 - [createNodeMiddleware()](#createnodemiddleware)
23 - [Webhook events](#webhook-events)
24 - [emitterEventNames](#emittereventnames)
25- [TypeScript](#typescript)
26 - [`EmitterWebhookEventName`](#emitterwebhookeventname)
27 - [`EmitterWebhookEvent`](#emitterwebhookevent)
28- [License](#license)
29
30<!-- tocstop -->
31
32`@octokit/webhooks` helps to handle webhook events received from GitHub.
33
34[GitHub webhooks](https://docs.github.com/webhooks/) can be registered in multiple ways
35
361. In repository or organization settings on [github.com](https://github.com/).
372. Using the REST API for [repositories](https://docs.github.com/rest/reference/repos#webhooks) or [organizations](https://docs.github.com/rest/reference/orgs#webhooks/)
383. By [creating a GitHub App](https://docs.github.com/developers/apps/creating-a-github-app).
39
40Note 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 to `application/json`, `application/x-www-form-urlencoded` is not supported.
41
42## Usage
43
44```js
45// install with: npm install @octokit/webhooks
46const { Webhooks, createNodeMiddleware } = require("@octokit/webhooks");
47const webhooks = new Webhooks({
48 secret: "mysecret",
49});
50
51webhooks.onAny(({ id, name, payload }) => {
52 console.log(name, "event received");
53});
54
55require("http").createServer(createNodeMiddleware(webhooks)).listen(3000);
56// can now receive webhook events at /api/github/webhooks
57```
58
59## Local development
60
61You can receive webhooks on your local machine or even browser using [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) and [smee.io](https://smee.io/).
62
63Go to [smee.io](https://smee.io/) and <kbd>Start a new channel</kbd>. Then copy the "Webhook Proxy URL" and
64
651. enter it in the GitHub App’s "Webhook URL" input
662. pass it to the [EventSource](https://github.com/EventSource/eventsource) constructor, see below
67
68```js
69const webhookProxyUrl = "https://smee.io/IrqK0nopGAOc847"; // replace with your own Webhook Proxy URL
70const source = new EventSource(webhookProxyUrl);
71source.onmessage = (event) => {
72 const webhookEvent = JSON.parse(event.data);
73 webhooks
74 .verifyAndReceive({
75 id: webhookEvent["x-request-id"],
76 name: webhookEvent["x-github-event"],
77 signature: webhookEvent["x-hub-signature"],
78 payload: webhookEvent.body,
79 })
80 .catch(console.error);
81};
82```
83
84`EventSource` is a native browser API and can be polyfilled for browsers that don’t support it. In node, you can use the [`eventsource`](https://github.com/EventSource/eventsource) package: install with `npm install eventsource`, then `const EventSource = require('eventsource')`
85
86## API
87
881. [Constructor](#constructor)
892. [webhooks.sign()](#webhookssign)
903. [webhooks.verify()](#webhooksverify)
914. [webhooks.verifyAndReceive()](#webhooksverifyandreceive)
925. [webhooks.receive()](#webhooksreceive)
936. [webhooks.on()](#webhookson)
947. [webhooks.onAny()](#webhooksonany)
958. [webhooks.onError()](#webhooksonerror)
969. [webhooks.removeListener()](#webhooksremovelistener)
9710. [createNodeMiddleware()](#createnodemiddleware)
9811. [Webhook events](#webhook-events)
9912. [emitterEventNames](#emittereventnames)
100
101### Constructor
102
103```js
104new Webhooks({ secret /*, transform */ });
105```
106
107<table width="100%">
108 <tbody valign="top">
109 <tr>
110 <td>
111 <code>
112 secret
113 </code>
114 <em>(String)</em>
115 </td>
116 <td>
117 <strong>Required.</strong>
118 Secret as configured in GitHub Settings.
119 </td>
120 </tr>
121 <tr>
122 <td>
123 <code>
124 transform
125 </code>
126 <em>(Function)</em>
127 </td>
128 <td>
129 Only relevant for <a href="#webhookson"><code>webhooks.on</code></a>.
130 Transform emitted event before calling handlers. Can be asynchronous.
131 </td>
132 </tr>
133 <tr>
134 <td>
135 <code>log</code>
136 <em>
137 object
138 </em>
139 </td>
140 <td>
141
142Used for internal logging. Defaults to [`console`](https://developer.mozilla.org/en-US/docs/Web/API/console) with `debug` and `info` doing nothing.
143
144</td>
145 </tr>
146 </tbody>
147</table>
148
149Returns the `webhooks` API.
150
151### webhooks.sign()
152
153```js
154webhooks.sign(eventPayload);
155```
156
157<table width="100%">
158 <tbody valign="top">
159 <tr>
160 <td>
161 <code>
162 eventPayload
163 </code>
164 <em>
165 (Object)
166 </em>
167 </td>
168 <td>
169 <strong>Required.</strong>
170 Webhook request payload as received from GitHub
171 </td>
172 </tr>
173 </tbody>
174</table>
175
176Returns a `signature` string. Throws error if `eventPayload` is not passed.
177
178The `sign` method can be imported as static method from [`@octokit/webhooks-methods`](https://github.com/octokit/webhooks-methods.js/#readme).
179
180### webhooks.verify()
181
182```js
183webhooks.verify(eventPayload, signature);
184```
185
186<table width="100%">
187 <tbody valign="top">
188 <tr>
189 <td>
190 <code>
191 eventPayload
192 </code>
193 <em>
194 (Object [deprecated] or String)
195 </em>
196 </td>
197 <td>
198 <strong>Required.</strong>
199 Webhook event request payload as received from GitHub.
200 </td>
201 </tr>
202 <tr>
203 <td>
204 <code>
205 signature
206 </code>
207 <em>
208 (String)
209 </em>
210 </td>
211 <td>
212 <strong>Required.</strong>
213 Signature string as calculated by <code><a href="#webhookssign">webhooks.sign()</a></code>.
214 </td>
215 </tr>
216 </tbody>
217</table>
218
219Returns `true` or `false`. Throws error if `eventPayload` or `signature` not passed.
220
221The `verify` method can be imported as static method from [`@octokit/webhooks-methods`](https://github.com/octokit/webhooks-methods.js/#readme).
222
223### webhooks.verifyAndReceive()
224
225```js
226webhooks.verifyAndReceive({ id, name, payload, signature });
227```
228
229<table width="100%">
230 <tbody valign="top">
231 <tr>
232 <td>
233 <code>
234 id
235 </code>
236 <em>
237 String
238 </em>
239 </td>
240 <td>
241 Unique webhook event request id
242 </td>
243 </tr>
244 <tr>
245 <td>
246 <code>
247 name
248 </code>
249 <em>
250 String
251 </em>
252 </td>
253 <td>
254 <strong>Required.</strong>
255 Name of the event. (Event names are set as <a href="https://docs.github.com/developers/webhooks-and-events/webhook-events-and-payloads#delivery-headers"><code>X-GitHub-Event</code> header</a>
256 in the webhook event request.)
257 </td>
258 </tr>
259 <tr>
260 <td>
261 <code>
262 payload
263 </code>
264 <em>
265 Object (deprecated) or String
266 </em>
267 </td>
268 <td>
269 <strong>Required.</strong>
270 Webhook event request payload as received from GitHub.
271 </td>
272 </tr>
273 <tr>
274 <td>
275 <code>
276 signature
277 </code>
278 <em>
279 (String)
280 </em>
281 </td>
282 <td>
283 <strong>Required.</strong>
284 Signature string as calculated by <code><a href="#webhookssign">webhooks.sign()</a></code>.
285 </td>
286 </tr>
287 </tbody>
288</table>
289
290Returns a promise.
291
292Verifies event using [webhooks.verify()](#webhooksverify), then handles the event using [webhooks.receive()](#webhooksreceive).
293
294Additionally, if verification fails, rejects the returned promise and emits an `error` event.
295
296Example
297
298```js
299const { Webhooks } = require("@octokit/webhooks");
300const webhooks = new Webhooks({
301 secret: "mysecret",
302});
303eventHandler.on("error", handleSignatureVerificationError);
304
305// put this inside your webhooks route handler
306eventHandler
307 .verifyAndReceive({
308 id: request.headers["x-github-delivery"],
309 name: request.headers["x-github-event"],
310 payload: request.body,
311 signature: request.headers["x-hub-signature-256"],
312 })
313 .catch(handleErrorsFromHooks);
314```
315
316### webhooks.receive()
317
318```js
319webhooks.receive({ id, name, payload });
320```
321
322<table width="100%">
323 <tbody valign="top">
324 <tr>
325 <td>
326 <code>
327 id
328 </code>
329 <em>
330 String
331 </em>
332 </td>
333 <td>
334 Unique webhook event request id
335 </td>
336 </tr>
337 <tr>
338 <td>
339 <code>
340 name
341 </code>
342 <em>
343 String
344 </em>
345 </td>
346 <td>
347 <strong>Required.</strong>
348 Name of the event. (Event names are set as <a href="https://docs.github.com/developers/webhooks-and-events/webhook-events-and-payloads#delivery-headers"><code>X-GitHub-Event</code> header</a>
349 in the webhook event request.)
350 </td>
351 </tr>
352 <tr>
353 <td>
354 <code>
355 payload
356 </code>
357 <em>
358 Object
359 </em>
360 </td>
361 <td>
362 <strong>Required.</strong>
363 Webhook event request payload as received from GitHub.
364 </td>
365 </tr>
366 </tbody>
367</table>
368
369Returns a promise. Runs all handlers set with [`webhooks.on()`](#webhookson) in parallel and waits for them to finish. If one of the handlers rejects or throws an error, then `webhooks.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.
370
371The `.receive()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
372
373### webhooks.on()
374
375```js
376webhooks.on(eventName, handler);
377webhooks.on(eventNames, handler);
378```
379
380<table width="100%">
381 <tbody valign="top">
382 <tr>
383 <td>
384 <code>
385 eventName
386 </code>
387 <em>
388 String
389 </em>
390 </td>
391 <td>
392 <strong>Required.</strong>
393 Name of the event. One of <a href="#webhook-events">GitHub's supported event names</a>, or (if the event has an action property) the name of an event followed by its action in the form of <code>&lt;event>.&lt;action></code>.
394 </td>
395 </tr>
396 <tr>
397 <td>
398 <code>
399 eventNames
400 </code>
401 <em>
402 Array
403 </em>
404 </td>
405 <td>
406 <strong>Required.</strong>
407 Array of event names.
408 </td>
409 </tr>
410 <tr>
411 <td>
412 <code>
413 handler
414 </code>
415 <em>
416 Function
417 </em>
418 </td>
419 <td>
420 <strong>Required.</strong>
421 Method to be run each time the event with the passed name is received.
422 the <code>handler</code> function can be an async function, throw an error or
423 return a Promise. The handler is called with an event object: <code>{id, name, payload}</code>.
424 </td>
425 </tr>
426 </tbody>
427</table>
428
429The `.on()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
430
431### webhooks.onAny()
432
433```js
434webhooks.onAny(handler);
435```
436
437<table width="100%">
438 <tbody valign="top">
439 <tr>
440 <td>
441 <code>
442 handler
443 </code>
444 <em>
445 Function
446 </em>
447 </td>
448 <td>
449 <strong>Required.</strong>
450 Method to be run each time any event is received.
451 the <code>handler</code> function can be an async function, throw an error or
452 return a Promise. The handler is called with an event object: <code>{id, name, payload}</code>.
453 </td>
454 </tr>
455 </tbody>
456</table>
457
458The `.onAny()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
459
460### webhooks.onError()
461
462```js
463webhooks.onError(handler);
464```
465
466If 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.
467
468Asynchronous `error` event handler are not blocking the `.receive()` method from completing.
469
470<table width="100%">
471 <tbody valign="top">
472 <tr>
473 <td>
474 <code>
475 handler
476 </code>
477 <em>
478 Function
479 </em>
480 </td>
481 <td>
482 <strong>Required.</strong>
483 Method to be run each time a webhook event handler throws an error or returns a promise that rejects.
484 The <code>handler</code> function can be an async function,
485 return a Promise. The handler is called with an error object that has a .event property which has all the information on the event: <code>{id, name, payload}</code>.
486 </td>
487 </tr>
488 </tbody>
489</table>
490
491The `.onError()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
492
493### webhooks.removeListener()
494
495```js
496webhooks.removeListener(eventName, handler);
497webhooks.removeListener(eventNames, handler);
498```
499
500<table width="100%">
501 <tbody valign="top">
502 <tr>
503 <td>
504 <code>
505 eventName
506 </code>
507 <em>
508 String
509 </em>
510 </td>
511 <td>
512 <strong>Required.</strong>
513 Name of the event. One of <a href="#webhook-events">GitHub's supported event names</a>, or (if the event has an action property) the name of an event followed by its action in the form of <code>&lt;event>.&lt;action></code>, or '*' for the <code>onAny()</code> method or 'error' for the <code>onError()</code> method.
514 </td>
515 </tr>
516 <tr>
517 <td>
518 <code>
519 eventNames
520 </code>
521 <em>
522 Array
523 </em>
524 </td>
525 <td>
526 <strong>Required.</strong>
527 Array of event names.
528 </td>
529 </tr>
530 <tr>
531 <td>
532 <code>
533 handler
534 </code>
535 <em>
536 Function
537 </em>
538 </td>
539 <td>
540 <strong>Required.</strong>
541 Method which was previously passed to <code><a href="webhookson">webhooks.on()</a></code>. If the same handler was registered multiple times for the same event, only the most recent handler gets removed.
542 </td>
543 </tr>
544 </tbody>
545</table>
546
547The `.removeListener()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
548
549### createNodeMiddleware()
550
551```js
552const { createServer } = require("http");
553const { Webhooks, createNodeMiddleware } = require("@octokit/webhooks");
554
555const webhooks = new Webhooks({
556 secret: "mysecret",
557});
558
559const middleware = createNodeMiddleware(webhooks, { path: "/" });
560
561createServer(middleware).listen(3000);
562// can now receive user authorization callbacks at POST /
563```
564
565<table width="100%">
566 <tbody valign="top">
567 <tr>
568 <td>
569 <code>webhooks</code>
570 <em>
571 Webhooks instance
572 </em>
573 </td>
574 <td>
575 <strong>Required.</strong>
576 </td>
577 </tr>
578 <tr>
579 <td>
580 <code>path</code>
581 <em>
582 string
583 </em>
584 </td>
585 <td>
586 Custom path to match requests against. Defaults to <code>/api/github/webhooks</code>.
587 </td>
588 </tr>
589 <tr>
590 <td>
591 <code>log</code>
592 <em>
593 object
594 </em>
595 </td>
596 <td>
597
598Used for internal logging. Defaults to [`console`](https://developer.mozilla.org/en-US/docs/Web/API/console) with `debug` and `info` doing nothing.
599
600</td>
601 </tr>
602 <tr>
603 <td>
604 <code>onUnhandledRequest (deprecated)</code>
605 <em>
606 function
607 </em>
608 </td>
609 <td>
610
611Defaults to
612
613```js
614function onUnhandledRequest(request, response) {
615 response.writeHead(400, {
616 "content-type": "application/json",
617 });
618 response.end(
619 JSON.stringify({
620 error: error.message,
621 })
622 );
623}
624```
625
626</td>
627 </tr>
628 <tbody>
629</table>
630
631### Webhook events
632
633See the full list of [event types with example payloads](https://docs.github.com/developers/webhooks-and-events/webhook-events-and-payloads/).
634
635If 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` and `installation.created`.
636
637<!-- autogenerated via scripts/generate-types.ts -->
638
639| Event | Actions |
640| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
641| [`branch_protection_rule`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#branch_protection_rule) | `created`<br>`deleted`<br>`edited` |
642| [`check_run`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#check_run) | `completed`<br>`created`<br>`requested_action`<br>`rerequested` |
643| [`check_suite`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#check_suite) | `completed`<br>`requested`<br>`rerequested` |
644| [`code_scanning_alert`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#code_scanning_alert) | `appeared_in_branch`<br>`closed_by_user`<br>`created`<br>`fixed`<br>`reopened`<br>`reopened_by_user` |
645| [`commit_comment`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#commit_comment) | `created` |
646| [`create`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#create) | |
647| [`delete`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#delete) | |
648| [`dependabot_alert`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#dependabot_alert) | `created`<br>`dismissed`<br>`fixed`<br>`reintroduced`<br>`reopened` |
649| [`deploy_key`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#deploy_key) | `created`<br>`deleted` |
650| [`deployment`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#deployment) | `created` |
651| [`deployment_status`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#deployment_status) | `created` |
652| [`discussion`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#discussion) | `answered`<br>`category_changed`<br>`created`<br>`deleted`<br>`edited`<br>`labeled`<br>`locked`<br>`pinned`<br>`transferred`<br>`unanswered`<br>`unlabeled`<br>`unlocked`<br>`unpinned` |
653| [`discussion_comment`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#discussion_comment) | `created`<br>`deleted`<br>`edited` |
654| [`fork`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#fork) | |
655| [`github_app_authorization`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#github_app_authorization) | `revoked` |
656| [`gollum`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#gollum) | |
657| [`installation`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#installation) | `created`<br>`deleted`<br>`new_permissions_accepted`<br>`suspend`<br>`unsuspend` |
658| [`installation_repositories`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#installation_repositories) | `added`<br>`removed` |
659| [`installation_target`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#installation_target) | `renamed` |
660| [`issue_comment`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#issue_comment) | `created`<br>`deleted`<br>`edited` |
661| [`issues`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#issues) | `assigned`<br>`closed`<br>`deleted`<br>`demilestoned`<br>`edited`<br>`labeled`<br>`locked`<br>`milestoned`<br>`opened`<br>`pinned`<br>`reopened`<br>`transferred`<br>`unassigned`<br>`unlabeled`<br>`unlocked`<br>`unpinned` |
662| [`label`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#label) | `created`<br>`deleted`<br>`edited` |
663| [`marketplace_purchase`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#marketplace_purchase) | `cancelled`<br>`changed`<br>`pending_change`<br>`pending_change_cancelled`<br>`purchased` |
664| [`member`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#member) | `added`<br>`edited`<br>`removed` |
665| [`membership`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#membership) | `added`<br>`removed` |
666| [`merge_group`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#merge_group) | `checks_requested` |
667| [`meta`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#meta) | `deleted` |
668| [`milestone`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#milestone) | `closed`<br>`created`<br>`deleted`<br>`edited`<br>`opened` |
669| [`org_block`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#org_block) | `blocked`<br>`unblocked` |
670| [`organization`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#organization) | `deleted`<br>`member_added`<br>`member_invited`<br>`member_removed`<br>`renamed` |
671| [`package`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#package) | `published`<br>`updated` |
672| [`page_build`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#page_build) | |
673| [`ping`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#ping) | |
674| [`project`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#project) | `closed`<br>`created`<br>`deleted`<br>`edited`<br>`reopened` |
675| [`project_card`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#project_card) | `converted`<br>`created`<br>`deleted`<br>`edited`<br>`moved` |
676| [`project_column`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#project_column) | `created`<br>`deleted`<br>`edited`<br>`moved` |
677| [`projects_v2_item`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#projects_v2_item) | `archived`<br>`converted`<br>`created`<br>`deleted`<br>`edited`<br>`reordered`<br>`restored` |
678| [`public`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#public) | |
679| [`pull_request`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request) | `assigned`<br>`auto_merge_disabled`<br>`auto_merge_enabled`<br>`closed`<br>`converted_to_draft`<br>`dequeued`<br>`edited`<br>`labeled`<br>`locked`<br>`opened`<br>`queued`<br>`ready_for_review`<br>`reopened`<br>`review_request_removed`<br>`review_requested`<br>`synchronize`<br>`unassigned`<br>`unlabeled`<br>`unlocked` |
680| [`pull_request_review`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request_review) | `dismissed`<br>`edited`<br>`submitted` |
681| [`pull_request_review_comment`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request_review_comment) | `created`<br>`deleted`<br>`edited` |
682| [`pull_request_review_thread`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request_review_thread) | `resolved`<br>`unresolved` |
683| [`push`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#push) | |
684| [`registry_package`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#registry_package) | `published`<br>`updated` |
685| [`release`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#release) | `created`<br>`deleted`<br>`edited`<br>`prereleased`<br>`published`<br>`released`<br>`unpublished` |
686| [`repository`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#repository) | `archived`<br>`created`<br>`deleted`<br>`edited`<br>`privatized`<br>`publicized`<br>`renamed`<br>`transferred`<br>`unarchived` |
687| [`repository_dispatch`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#repository_dispatch) | |
688| [`repository_import`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#repository_import) | |
689| [`repository_vulnerability_alert`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#repository_vulnerability_alert) | `create`<br>`dismiss`<br>`reopen`<br>`resolve` |
690| [`secret_scanning_alert`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#secret_scanning_alert) | `created`<br>`reopened`<br>`resolved` |
691| [`security_advisory`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#security_advisory) | `performed`<br>`published`<br>`updated`<br>`withdrawn` |
692| [`sponsorship`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#sponsorship) | `cancelled`<br>`created`<br>`edited`<br>`pending_cancellation`<br>`pending_tier_change`<br>`tier_changed` |
693| [`star`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#star) | `created`<br>`deleted` |
694| [`status`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#status) | |
695| [`team`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#team) | `added_to_repository`<br>`created`<br>`deleted`<br>`edited`<br>`removed_from_repository` |
696| [`team_add`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#team_add) | |
697| [`watch`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#watch) | `started` |
698| [`workflow_dispatch`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_dispatch) | |
699| [`workflow_job`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_job) | `completed`<br>`in_progress`<br>`queued` |
700| [`workflow_run`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_run) | `completed`<br>`in_progress`<br>`requested` |
701
702<!-- /autogenerated via scripts/generate-types.ts -->
703
704### emitterEventNames
705
706A read only tuple containing all the possible combinations of the webhook events + actions listed above. This might be useful in GUI and input validation.
707
708```js
709import { emitterEventNames } from "@octokit/webhooks";
710emitterEventNames; // ["check_run", "check_run.completed", ...]
711```
712
713## TypeScript
714
715The types for the webhook payloads are sourced from [`@octokit/webhooks-types`](https://github.com/octokit/webhooks/tree/main/payload-types),
716which can be used by themselves.
717
718In addition to these types, `@octokit/webhooks` exports 2 types specific to itself:
719
720Note 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.
721
722**⚠️ Caution ⚠️**: Webhooks Types are expected to be used with the [`strictNullChecks` option](https://www.typescriptlang.org/tsconfig#strictNullChecks) enabled in your `tsconfig`. If you don't have this option enabled, there's the possibility that you get `never` as the inferred type in some use cases. See [octokit/webhooks#395](https://github.com/octokit/webhooks/issues/395) for details.
723
724### `EmitterWebhookEventName`
725
726A 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"`.
727
728### `EmitterWebhookEvent`
729
730The object that is emitted by `@octokit/webhooks` as an event; made up of an `id`, `name`, and `payload` properties.
731An optional generic parameter can be passed to narrow the type of the `name` and `payload` properties based on event names or event/action combinations, e.g. `EmitterWebhookEvent<"check_run" | "code_scanning_alert.fixed">`.
732
733## License
734
735[MIT](LICENSE.md)