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 |
|
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 |
|
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 |
|
36 | 1. In repository or organization settings on [github.com](https://github.com/).
|
37 | 2. Using the REST API for [repositories](https://docs.github.com/rest/reference/repos#webhooks) or [organizations](https://docs.github.com/rest/reference/orgs#webhooks/)
|
38 | 3. By [creating a GitHub App](https://docs.github.com/developers/apps/creating-a-github-app).
|
39 |
|
40 | 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 to `application/json`, `application/x-www-form-urlencoded` is not supported.
|
41 |
|
42 | ## Usage
|
43 |
|
44 | ```js
|
45 | // install with: npm install @octokit/webhooks
|
46 | const { Webhooks, createNodeMiddleware } = require("@octokit/webhooks");
|
47 | const webhooks = new Webhooks({
|
48 | secret: "mysecret",
|
49 | });
|
50 |
|
51 | webhooks.onAny(({ id, name, payload }) => {
|
52 | console.log(name, "event received");
|
53 | });
|
54 |
|
55 | require("http").createServer(createNodeMiddleware(webhooks)).listen(3000);
|
56 | // can now receive webhook events at /api/github/webhooks
|
57 | ```
|
58 |
|
59 | ## Local development
|
60 |
|
61 | You 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 |
|
63 | Go to [smee.io](https://smee.io/) and <kbd>Start a new channel</kbd>. Then copy the "Webhook Proxy URL" and
|
64 |
|
65 | 1. enter it in the GitHub App’s "Webhook URL" input
|
66 | 2. pass it to the [EventSource](https://github.com/EventSource/eventsource) constructor, see below
|
67 |
|
68 | ```js
|
69 | const webhookProxyUrl = "https://smee.io/IrqK0nopGAOc847"; // replace with your own Webhook Proxy URL
|
70 | const source = new EventSource(webhookProxyUrl);
|
71 | source.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 |
|
88 | 1. [Constructor](#constructor)
|
89 | 2. [webhooks.sign()](#webhookssign)
|
90 | 3. [webhooks.verify()](#webhooksverify)
|
91 | 4. [webhooks.verifyAndReceive()](#webhooksverifyandreceive)
|
92 | 5. [webhooks.receive()](#webhooksreceive)
|
93 | 6. [webhooks.on()](#webhookson)
|
94 | 7. [webhooks.onAny()](#webhooksonany)
|
95 | 8. [webhooks.onError()](#webhooksonerror)
|
96 | 9. [webhooks.removeListener()](#webhooksremovelistener)
|
97 | 10. [createNodeMiddleware()](#createnodemiddleware)
|
98 | 11. [Webhook events](#webhook-events)
|
99 | 12. [emitterEventNames](#emittereventnames)
|
100 |
|
101 | ### Constructor
|
102 |
|
103 | ```js
|
104 | new 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 |
|
142 | Used 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 |
|
149 | Returns the `webhooks` API.
|
150 |
|
151 | ### webhooks.sign()
|
152 |
|
153 | ```js
|
154 | webhooks.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 |
|
176 | Returns a `signature` string. Throws error if `eventPayload` is not passed.
|
177 |
|
178 | The `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
|
183 | webhooks.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 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 |
|
219 | Returns `true` or `false`. Throws error if `eventPayload` or `signature` not passed.
|
220 |
|
221 | The `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
|
226 | webhooks.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 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 |
|
290 | Returns a promise.
|
291 |
|
292 | Verifies event using [webhooks.verify()](#webhooksverify), then handles the event using [webhooks.receive()](#webhooksreceive).
|
293 |
|
294 | Additionally, if verification fails, rejects the returned promise and emits an `error` event.
|
295 |
|
296 | Example
|
297 |
|
298 | ```js
|
299 | const { Webhooks } = require("@octokit/webhooks");
|
300 | const webhooks = new Webhooks({
|
301 | secret: "mysecret",
|
302 | });
|
303 | eventHandler.on("error", handleSignatureVerificationError);
|
304 |
|
305 | // put this inside your webhooks route handler
|
306 | eventHandler
|
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
|
319 | webhooks.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 |
|
369 | Returns 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 |
|
371 | The `.receive()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
|
372 |
|
373 | ### webhooks.on()
|
374 |
|
375 | ```js
|
376 | webhooks.on(eventName, handler);
|
377 | webhooks.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><event>.<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 |
|
429 | The `.on()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
|
430 |
|
431 | ### webhooks.onAny()
|
432 |
|
433 | ```js
|
434 | webhooks.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 |
|
458 | The `.onAny()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
|
459 |
|
460 | ### webhooks.onError()
|
461 |
|
462 | ```js
|
463 | webhooks.onError(handler);
|
464 | ```
|
465 |
|
466 | 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.
|
467 |
|
468 | Asynchronous `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 |
|
491 | The `.onError()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
|
492 |
|
493 | ### webhooks.removeListener()
|
494 |
|
495 | ```js
|
496 | webhooks.removeListener(eventName, handler);
|
497 | webhooks.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><event>.<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 |
|
547 | The `.removeListener()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
|
548 |
|
549 | ### createNodeMiddleware()
|
550 |
|
551 | ```js
|
552 | const { createServer } = require("http");
|
553 | const { Webhooks, createNodeMiddleware } = require("@octokit/webhooks");
|
554 |
|
555 | const webhooks = new Webhooks({
|
556 | secret: "mysecret",
|
557 | });
|
558 |
|
559 | const middleware = createNodeMiddleware(webhooks, { path: "/" });
|
560 |
|
561 | createServer(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 |
|
598 | Used 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</code>
|
605 | <em>
|
606 | function
|
607 | </em>
|
608 | </td>
|
609 | <td>
|
610 |
|
611 | Defaults to
|
612 |
|
613 | ```js
|
614 | function 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 |
|
633 | See the full list of [event types with example payloads](https://docs.github.com/developers/webhooks-and-events/webhook-events-and-payloads/).
|
634 |
|
635 | 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` and `installation.created`.
|
636 |
|
637 |
|
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 | | [`deploy_key`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#deploy_key) | `created`<br>`deleted` |
|
649 | | [`deployment`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#deployment) | `created` |
|
650 | | [`deployment_status`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#deployment_status) | `created` |
|
651 | | [`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` |
|
652 | | [`discussion_comment`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#discussion_comment) | `created`<br>`deleted`<br>`edited` |
|
653 | | [`fork`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#fork) | |
|
654 | | [`github_app_authorization`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#github_app_authorization) | `revoked` |
|
655 | | [`gollum`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#gollum) | |
|
656 | | [`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` |
|
657 | | [`installation_repositories`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#installation_repositories) | `added`<br>`removed` |
|
658 | | [`issue_comment`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#issue_comment) | `created`<br>`deleted`<br>`edited` |
|
659 | | [`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` |
|
660 | | [`label`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#label) | `created`<br>`deleted`<br>`edited` |
|
661 | | [`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` |
|
662 | | [`member`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#member) | `added`<br>`edited`<br>`removed` |
|
663 | | [`membership`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#membership) | `added`<br>`removed` |
|
664 | | [`meta`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#meta) | `deleted` |
|
665 | | [`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` |
|
666 | | [`org_block`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#org_block) | `blocked`<br>`unblocked` |
|
667 | | [`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` |
|
668 | | [`package`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#package) | `published`<br>`updated` |
|
669 | | [`page_build`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#page_build) | |
|
670 | | [`ping`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#ping) | |
|
671 | | [`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` |
|
672 | | [`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` |
|
673 | | [`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` |
|
674 | | [`public`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#public) | |
|
675 | | [`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>`edited`<br>`labeled`<br>`locked`<br>`opened`<br>`ready_for_review`<br>`reopened`<br>`review_request_removed`<br>`review_requested`<br>`synchronize`<br>`unassigned`<br>`unlabeled`<br>`unlocked` |
|
676 | | [`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` |
|
677 | | [`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` |
|
678 | | [`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` |
|
679 | | [`push`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#push) | |
|
680 | | [`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` |
|
681 | | [`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` |
|
682 | | [`repository_dispatch`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#repository_dispatch) | |
|
683 | | [`repository_import`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#repository_import) | |
|
684 | | [`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` |
|
685 | | [`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` |
|
686 | | [`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` |
|
687 | | [`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` |
|
688 | | [`star`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#star) | `created`<br>`deleted` |
|
689 | | [`status`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#status) | |
|
690 | | [`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` |
|
691 | | [`team_add`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#team_add) | |
|
692 | | [`watch`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#watch) | `started` |
|
693 | | [`workflow_dispatch`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_dispatch) | |
|
694 | | [`workflow_job`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_job) | `completed`<br>`in_progress`<br>`queued` |
|
695 | | [`workflow_run`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_run) | `completed`<br>`requested` |
|
696 |
|
697 |
|
698 |
|
699 | ### emitterEventNames
|
700 |
|
701 | 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.
|
702 |
|
703 | ```js
|
704 | import { emitterEventNames } from "@octokit/webhooks";
|
705 | emitterEventNames; // ["check_run", "check_run.completed", ...]
|
706 | ```
|
707 |
|
708 | ## TypeScript
|
709 |
|
710 | The types for the webhook payloads are sourced from [`@octokit/webhooks-types`](https://github.com/octokit/webhooks/tree/master/payload-types),
|
711 | which can be used by themselves.
|
712 |
|
713 | In addition to these types, `@octokit/webhooks` exports 2 types specific to itself:
|
714 |
|
715 | 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.
|
716 |
|
717 | ### `EmitterWebhookEventName`
|
718 |
|
719 | 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"`.
|
720 |
|
721 | ### `EmitterWebhookEvent`
|
722 |
|
723 | The object that is emitted by `@octokit/webhooks` as an event; made up of an `id`, `name`, and `payload` properties.
|
724 | An 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">`.
|
725 |
|
726 | ## License
|
727 |
|
728 | [MIT](LICENSE.md)
|