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 | - [TypeScript](#typescript)
|
25 | - [`EmitterWebhookEventName`](#emitterwebhookeventname)
|
26 | - [`EmitterWebhookEvent`](#emitterwebhookevent)
|
27 | - [License](#license)
|
28 |
|
29 |
|
30 |
|
31 | `@octokit/webhooks` helps to handle webhook events received from GitHub.
|
32 |
|
33 | [GitHub webhooks](https://docs.github.com/webhooks/) can be registered in multiple ways
|
34 |
|
35 | 1. In repository or organization settings on [github.com](https://github.com/).
|
36 | 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/)
|
37 | 3. By [creating a GitHub App](https://docs.github.com/developers/apps/creating-a-github-app).
|
38 |
|
39 | 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.
|
40 |
|
41 | ## Usage
|
42 |
|
43 | ```js
|
44 | // install with: npm install @octokit/webhooks
|
45 | const { Webhooks, createNodeMiddleware } = require("@octokit/webhooks");
|
46 | const webhooks = new Webhooks({
|
47 | secret: "mysecret",
|
48 | });
|
49 |
|
50 | webhooks.onAny(({ id, name, payload }) => {
|
51 | console.log(name, "event received");
|
52 | });
|
53 |
|
54 | require("http").createServer(createNodeMiddleware(webhooks)).listen(3000);
|
55 | // can now receive webhook events at /api/github/webhooks
|
56 | ```
|
57 |
|
58 | ## Local development
|
59 |
|
60 | 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/).
|
61 |
|
62 | Go to [smee.io](https://smee.io/) and <kbd>Start a new channel</kbd>. Then copy the "Webhook Proxy URL" and
|
63 |
|
64 | 1. enter it in the GitHub App’s "Webhook URL" input
|
65 | 2. pass it to the [EventSource](https://github.com/EventSource/eventsource) constructor, see below
|
66 |
|
67 | ```js
|
68 | const webhookProxyUrl = "https://smee.io/IrqK0nopGAOc847"; // replace with your own Webhook Proxy URL
|
69 | const source = new EventSource(webhookProxyUrl);
|
70 | source.onmessage = (event) => {
|
71 | const webhookEvent = JSON.parse(event.data);
|
72 | webhooks
|
73 | .verifyAndReceive({
|
74 | id: webhookEvent["x-request-id"],
|
75 | name: webhookEvent["x-github-event"],
|
76 | signature: webhookEvent["x-hub-signature"],
|
77 | payload: webhookEvent.body,
|
78 | })
|
79 | .catch(console.error);
|
80 | };
|
81 | ```
|
82 |
|
83 | `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')`
|
84 |
|
85 | ## API
|
86 |
|
87 | 1. [Constructor](#constructor)
|
88 | 2. [webhooks.sign()](#webhookssign)
|
89 | 3. [webhooks.verify()](#webhooksverify)
|
90 | 4. [webhooks.verifyAndReceive()](#webhooksverifyandreceive)
|
91 | 5. [webhooks.receive()](#webhooksreceive)
|
92 | 6. [webhooks.on()](#webhookson)
|
93 | 7. [webhooks.onAny()](#webhooksonany)
|
94 | 8. [webhooks.onError()](#webhooksonerror)
|
95 | 9. [webhooks.removeListener()](#webhooksremovelistener)
|
96 | 10. [createNodeMiddleware()](#createnodemiddleware)
|
97 | 11. [Webhook events](#webhook-events)
|
98 |
|
99 | ### Constructor
|
100 |
|
101 | ```js
|
102 | new Webhooks({ secret /*, transform */ });
|
103 | ```
|
104 |
|
105 | <table width="100%">
|
106 | <tbody valign="top">
|
107 | <tr>
|
108 | <td>
|
109 | <code>
|
110 | secret
|
111 | </code>
|
112 | <em>(String)</em>
|
113 | </td>
|
114 | <td>
|
115 | <strong>Required.</strong>
|
116 | Secret as configured in GitHub Settings.
|
117 | </td>
|
118 | </tr>
|
119 | <tr>
|
120 | <td>
|
121 | <code>
|
122 | transform
|
123 | </code>
|
124 | <em>(Function)</em>
|
125 | </td>
|
126 | <td>
|
127 | Only relevant for <a href="#webhookson"><code>webhooks.on</code></a>.
|
128 | Transform emitted event before calling handlers. Can be asynchronous.
|
129 | </td>
|
130 | </tr>
|
131 | <tr>
|
132 | <td>
|
133 | <code>log</code>
|
134 | <em>
|
135 | object
|
136 | </em>
|
137 | </td>
|
138 | <td>
|
139 |
|
140 | Used for internal logging. Defaults to [`console`](https://developer.mozilla.org/en-US/docs/Web/API/console) with `debug` and `info` doing nothing.
|
141 |
|
142 | </td>
|
143 | </tr>
|
144 | </tbody>
|
145 | </table>
|
146 |
|
147 | Returns the `webhooks` API.
|
148 |
|
149 | ### webhooks.sign()
|
150 |
|
151 | ```js
|
152 | webhooks.sign(eventPayload);
|
153 | ```
|
154 |
|
155 | <table width="100%">
|
156 | <tbody valign="top">
|
157 | <tr>
|
158 | <td>
|
159 | <code>
|
160 | eventPayload
|
161 | </code>
|
162 | <em>
|
163 | (Object)
|
164 | </em>
|
165 | </td>
|
166 | <td>
|
167 | <strong>Required.</strong>
|
168 | Webhook request payload as received from GitHub
|
169 | </td>
|
170 | </tr>
|
171 | </tbody>
|
172 | </table>
|
173 |
|
174 | Returns a `signature` string. Throws error if `eventPayload` is not passed.
|
175 |
|
176 | The `sign` method can be imported as static method from [`@octokit/webhooks-methods`](https://github.com/octokit/webhooks-methods.js/#readme).
|
177 |
|
178 | ### webhooks.verify()
|
179 |
|
180 | ```js
|
181 | webhooks.verify(eventPayload, signature);
|
182 | ```
|
183 |
|
184 | <table width="100%">
|
185 | <tbody valign="top">
|
186 | <tr>
|
187 | <td>
|
188 | <code>
|
189 | eventPayload
|
190 | </code>
|
191 | <em>
|
192 | (Object)
|
193 | </em>
|
194 | </td>
|
195 | <td>
|
196 | <strong>Required.</strong>
|
197 | Webhook event request payload as received from GitHub.
|
198 | </td>
|
199 | </tr>
|
200 | <tr>
|
201 | <td>
|
202 | <code>
|
203 | signature
|
204 | </code>
|
205 | <em>
|
206 | (String)
|
207 | </em>
|
208 | </td>
|
209 | <td>
|
210 | <strong>Required.</strong>
|
211 | Signature string as calculated by <code><a href="#webhookssign">webhooks.sign()</a></code>.
|
212 | </td>
|
213 | </tr>
|
214 | </tbody>
|
215 | </table>
|
216 |
|
217 | Returns `true` or `false`. Throws error if `eventPayload` or `signature` not passed.
|
218 |
|
219 | The `verify` method can be imported as static method from [`@octokit/webhooks-methods`](https://github.com/octokit/webhooks-methods.js/#readme).
|
220 |
|
221 | ### webhooks.verifyAndReceive()
|
222 |
|
223 | ```js
|
224 | webhooks.verifyAndReceive({ id, name, payload, signature });
|
225 | ```
|
226 |
|
227 | <table width="100%">
|
228 | <tbody valign="top">
|
229 | <tr>
|
230 | <td>
|
231 | <code>
|
232 | id
|
233 | </code>
|
234 | <em>
|
235 | String
|
236 | </em>
|
237 | </td>
|
238 | <td>
|
239 | Unique webhook event request id
|
240 | </td>
|
241 | </tr>
|
242 | <tr>
|
243 | <td>
|
244 | <code>
|
245 | name
|
246 | </code>
|
247 | <em>
|
248 | String
|
249 | </em>
|
250 | </td>
|
251 | <td>
|
252 | <strong>Required.</strong>
|
253 | 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>
|
254 | in the webhook event request.)
|
255 | </td>
|
256 | </tr>
|
257 | <tr>
|
258 | <td>
|
259 | <code>
|
260 | payload
|
261 | </code>
|
262 | <em>
|
263 | Object
|
264 | </em>
|
265 | </td>
|
266 | <td>
|
267 | <strong>Required.</strong>
|
268 | Webhook event request payload as received from GitHub.
|
269 | </td>
|
270 | </tr>
|
271 | <tr>
|
272 | <td>
|
273 | <code>
|
274 | signature
|
275 | </code>
|
276 | <em>
|
277 | (String)
|
278 | </em>
|
279 | </td>
|
280 | <td>
|
281 | <strong>Required.</strong>
|
282 | Signature string as calculated by <code><a href="#webhookssign">webhooks.sign()</a></code>.
|
283 | </td>
|
284 | </tr>
|
285 | </tbody>
|
286 | </table>
|
287 |
|
288 | Returns a promise.
|
289 |
|
290 | Verifies event using [webhooks.verify()](#webhooksverify), then handles the event using [webhooks.receive()](#webhooksreceive).
|
291 |
|
292 | Additionally, if verification fails, rejects the returned promise and emits an `error` event.
|
293 |
|
294 | Example
|
295 |
|
296 | ```js
|
297 | const { Webhooks } = require("@octokit/webhooks");
|
298 | const webhooks = new Webhooks({
|
299 | secret: "mysecret",
|
300 | });
|
301 | eventHandler.on("error", handleSignatureVerificationError);
|
302 |
|
303 | // put this inside your webhooks route handler
|
304 | eventHandler
|
305 | .verifyAndReceive({
|
306 | id: request.headers["x-github-delivery"],
|
307 | name: request.headers["x-github-event"],
|
308 | payload: request.body,
|
309 | signature: request.headers["x-hub-signature-256"],
|
310 | })
|
311 | .catch(handleErrorsFromHooks);
|
312 | ```
|
313 |
|
314 | ### webhooks.receive()
|
315 |
|
316 | ```js
|
317 | webhooks.receive({ id, name, payload });
|
318 | ```
|
319 |
|
320 | <table width="100%">
|
321 | <tbody valign="top">
|
322 | <tr>
|
323 | <td>
|
324 | <code>
|
325 | id
|
326 | </code>
|
327 | <em>
|
328 | String
|
329 | </em>
|
330 | </td>
|
331 | <td>
|
332 | Unique webhook event request id
|
333 | </td>
|
334 | </tr>
|
335 | <tr>
|
336 | <td>
|
337 | <code>
|
338 | name
|
339 | </code>
|
340 | <em>
|
341 | String
|
342 | </em>
|
343 | </td>
|
344 | <td>
|
345 | <strong>Required.</strong>
|
346 | 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>
|
347 | in the webhook event request.)
|
348 | </td>
|
349 | </tr>
|
350 | <tr>
|
351 | <td>
|
352 | <code>
|
353 | payload
|
354 | </code>
|
355 | <em>
|
356 | Object
|
357 | </em>
|
358 | </td>
|
359 | <td>
|
360 | <strong>Required.</strong>
|
361 | Webhook event request payload as received from GitHub.
|
362 | </td>
|
363 | </tr>
|
364 | </tbody>
|
365 | </table>
|
366 |
|
367 | 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.
|
368 |
|
369 | The `.receive()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
|
370 |
|
371 | ### webhooks.on()
|
372 |
|
373 | ```js
|
374 | webhooks.on(eventName, handler);
|
375 | webhooks.on(eventNames, handler);
|
376 | ```
|
377 |
|
378 | <table width="100%">
|
379 | <tbody valign="top">
|
380 | <tr>
|
381 | <td>
|
382 | <code>
|
383 | eventName
|
384 | </code>
|
385 | <em>
|
386 | String
|
387 | </em>
|
388 | </td>
|
389 | <td>
|
390 | <strong>Required.</strong>
|
391 | 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>.
|
392 | </td>
|
393 | </tr>
|
394 | <tr>
|
395 | <td>
|
396 | <code>
|
397 | eventNames
|
398 | </code>
|
399 | <em>
|
400 | Array
|
401 | </em>
|
402 | </td>
|
403 | <td>
|
404 | <strong>Required.</strong>
|
405 | Array of event names.
|
406 | </td>
|
407 | </tr>
|
408 | <tr>
|
409 | <td>
|
410 | <code>
|
411 | handler
|
412 | </code>
|
413 | <em>
|
414 | Function
|
415 | </em>
|
416 | </td>
|
417 | <td>
|
418 | <strong>Required.</strong>
|
419 | Method to be run each time the event with the passed name is received.
|
420 | the <code>handler</code> function can be an async function, throw an error or
|
421 | return a Promise. The handler is called with an event object: <code>{id, name, payload}</code>.
|
422 | </td>
|
423 | </tr>
|
424 | </tbody>
|
425 | </table>
|
426 |
|
427 | The `.on()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
|
428 |
|
429 | ### webhooks.onAny()
|
430 |
|
431 | ```js
|
432 | webhooks.onAny(handler);
|
433 | ```
|
434 |
|
435 | <table width="100%">
|
436 | <tbody valign="top">
|
437 | <tr>
|
438 | <td>
|
439 | <code>
|
440 | handler
|
441 | </code>
|
442 | <em>
|
443 | Function
|
444 | </em>
|
445 | </td>
|
446 | <td>
|
447 | <strong>Required.</strong>
|
448 | Method to be run each time any event is received.
|
449 | the <code>handler</code> function can be an async function, throw an error or
|
450 | return a Promise. The handler is called with an event object: <code>{id, name, payload}</code>.
|
451 | </td>
|
452 | </tr>
|
453 | </tbody>
|
454 | </table>
|
455 |
|
456 | The `.onAny()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
|
457 |
|
458 | ### webhooks.onError()
|
459 |
|
460 | ```js
|
461 | webhooks.onError(handler);
|
462 | ```
|
463 |
|
464 | 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.
|
465 |
|
466 | Asynchronous `error` event handler are not blocking the `.receive()` method from completing.
|
467 |
|
468 | <table width="100%">
|
469 | <tbody valign="top">
|
470 | <tr>
|
471 | <td>
|
472 | <code>
|
473 | handler
|
474 | </code>
|
475 | <em>
|
476 | Function
|
477 | </em>
|
478 | </td>
|
479 | <td>
|
480 | <strong>Required.</strong>
|
481 | Method to be run each time a webhook event handler throws an error or returns a promise that rejects.
|
482 | The <code>handler</code> function can be an async function,
|
483 | 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>.
|
484 | </td>
|
485 | </tr>
|
486 | </tbody>
|
487 | </table>
|
488 |
|
489 | The `.onError()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
|
490 |
|
491 | ### webhooks.removeListener()
|
492 |
|
493 | ```js
|
494 | webhooks.removeListener(eventName, handler);
|
495 | webhooks.removeListener(eventNames, handler);
|
496 | ```
|
497 |
|
498 | <table width="100%">
|
499 | <tbody valign="top">
|
500 | <tr>
|
501 | <td>
|
502 | <code>
|
503 | eventName
|
504 | </code>
|
505 | <em>
|
506 | String
|
507 | </em>
|
508 | </td>
|
509 | <td>
|
510 | <strong>Required.</strong>
|
511 | 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.
|
512 | </td>
|
513 | </tr>
|
514 | <tr>
|
515 | <td>
|
516 | <code>
|
517 | eventNames
|
518 | </code>
|
519 | <em>
|
520 | Array
|
521 | </em>
|
522 | </td>
|
523 | <td>
|
524 | <strong>Required.</strong>
|
525 | Array of event names.
|
526 | </td>
|
527 | </tr>
|
528 | <tr>
|
529 | <td>
|
530 | <code>
|
531 | handler
|
532 | </code>
|
533 | <em>
|
534 | Function
|
535 | </em>
|
536 | </td>
|
537 | <td>
|
538 | <strong>Required.</strong>
|
539 | 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.
|
540 | </td>
|
541 | </tr>
|
542 | </tbody>
|
543 | </table>
|
544 |
|
545 | The `.removeListener()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
|
546 |
|
547 | ### createNodeMiddleware()
|
548 |
|
549 | ```js
|
550 | const { createServer } = require("http");
|
551 | const { Webhooks, createNodeMiddleware } = require("@octokit/webhooks");
|
552 |
|
553 | const webhooks = new Webhooks({
|
554 | secret: "mysecret",
|
555 | });
|
556 |
|
557 | const middleware = createNodeMiddleware(webhooks, { path: "/" });
|
558 |
|
559 | createServer(middleware).listen(3000);
|
560 | // can now receive user authorization callbacks at POST /
|
561 | ```
|
562 |
|
563 | <table width="100%">
|
564 | <tbody valign="top">
|
565 | <tr>
|
566 | <td>
|
567 | <code>webhooks</code>
|
568 | <em>
|
569 | Webhooks instance
|
570 | </em>
|
571 | </td>
|
572 | <td>
|
573 | <strong>Required.</strong>
|
574 | </td>
|
575 | </tr>
|
576 | <tr>
|
577 | <td>
|
578 | <code>path</code>
|
579 | <em>
|
580 | string
|
581 | </em>
|
582 | </td>
|
583 | <td>
|
584 | Custom path to match requests against. Defaults to <code>/api/github/webhooks</code>.
|
585 | </td>
|
586 | </tr>
|
587 | <tr>
|
588 | <td>
|
589 | <code>log</code>
|
590 | <em>
|
591 | object
|
592 | </em>
|
593 | </td>
|
594 | <td>
|
595 |
|
596 | Used for internal logging. Defaults to [`console`](https://developer.mozilla.org/en-US/docs/Web/API/console) with `debug` and `info` doing nothing.
|
597 |
|
598 | </td>
|
599 | </tr>
|
600 | <tr>
|
601 | <td>
|
602 | <code>onUnhandledRequest</code>
|
603 | <em>
|
604 | function
|
605 | </em>
|
606 | </td>
|
607 | <td>
|
608 |
|
609 | Defaults to
|
610 |
|
611 | ```js
|
612 | function onUnhandledRequest(request, response) {
|
613 | response.writeHead(400, {
|
614 | "content-type": "application/json",
|
615 | });
|
616 | response.end(
|
617 | JSON.stringify({
|
618 | error: error.message,
|
619 | })
|
620 | );
|
621 | }
|
622 | ```
|
623 |
|
624 | </td>
|
625 | </tr>
|
626 | <tbody>
|
627 | </table>
|
628 |
|
629 | ### Webhook events
|
630 |
|
631 | See the full list of [event types with example payloads](https://docs.github.com/developers/webhooks-and-events/webhook-events-and-payloads/).
|
632 |
|
633 | 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`.
|
634 |
|
635 |
|
636 |
|
637 | | Event | Actions |
|
638 | | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
639 | | [`check_run`](https://developer.github.com/v3/activity/events/types/#checkrunevent) | `completed`<br>`created`<br>`requested_action`<br>`rerequested` |
|
640 | | [`check_suite`](https://developer.github.com/v3/activity/events/types/#checksuiteevent) | `completed`<br>`requested`<br>`rerequested` |
|
641 | | [`code_scanning_alert`](https://developer.github.com/v3/activity/events/types/#codescanningalertevent) | `appeared_in_branch`<br>`closed_by_user`<br>`created`<br>`fixed`<br>`reopened`<br>`reopened_by_user` |
|
642 | | [`commit_comment`](https://developer.github.com/v3/activity/events/types/#commitcommentevent) | `created` |
|
643 | | [`content_reference`](https://developer.github.com/v3/activity/events/types/#contentreferenceevent) | `created` |
|
644 | | [`create`](https://developer.github.com/v3/activity/events/types/#createevent) | |
|
645 | | [`delete`](https://developer.github.com/v3/activity/events/types/#deleteevent) | |
|
646 | | [`deploy_key`](https://developer.github.com/v3/activity/events/types/#deploykeyevent) | `created`<br>`deleted` |
|
647 | | [`deployment`](https://developer.github.com/v3/activity/events/types/#deploymentevent) | `created` |
|
648 | | [`deployment_status`](https://developer.github.com/v3/activity/events/types/#deploymentstatusevent) | `created` |
|
649 | | [`discussion`](https://developer.github.com/v3/activity/events/types/#discussionevent) | `answered`<br>`category_changed`<br>`created`<br>`deleted`<br>`edited`<br>`locked`<br>`pinned`<br>`transferred`<br>`unanswered`<br>`unlocked`<br>`unpinned` |
|
650 | | [`discussion_comment`](https://developer.github.com/v3/activity/events/types/#discussioncommentevent) | `created`<br>`deleted`<br>`edited` |
|
651 | | [`fork`](https://developer.github.com/v3/activity/events/types/#forkevent) | |
|
652 | | [`github_app_authorization`](https://developer.github.com/v3/activity/events/types/#githubappauthorizationevent) | `revoked` |
|
653 | | [`gollum`](https://developer.github.com/v3/activity/events/types/#gollumevent) | |
|
654 | | [`installation`](https://developer.github.com/v3/activity/events/types/#installationevent) | `created`<br>`deleted`<br>`new_permissions_accepted`<br>`suspend`<br>`unsuspend` |
|
655 | | [`installation_repositories`](https://developer.github.com/v3/activity/events/types/#installationrepositoriesevent) | `added`<br>`removed` |
|
656 | | [`issue_comment`](https://developer.github.com/v3/activity/events/types/#issuecommentevent) | `created`<br>`deleted`<br>`edited` |
|
657 | | [`issues`](https://developer.github.com/v3/activity/events/types/#issuesevent) | `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` |
|
658 | | [`label`](https://developer.github.com/v3/activity/events/types/#labelevent) | `created`<br>`deleted`<br>`edited` |
|
659 | | [`marketplace_purchase`](https://developer.github.com/v3/activity/events/types/#marketplacepurchaseevent) | `cancelled`<br>`changed`<br>`pending_change`<br>`pending_change_cancelled`<br>`purchased` |
|
660 | | [`member`](https://developer.github.com/v3/activity/events/types/#memberevent) | `added`<br>`edited`<br>`removed` |
|
661 | | [`membership`](https://developer.github.com/v3/activity/events/types/#membershipevent) | `added`<br>`removed` |
|
662 | | [`meta`](https://developer.github.com/v3/activity/events/types/#metaevent) | `deleted` |
|
663 | | [`milestone`](https://developer.github.com/v3/activity/events/types/#milestoneevent) | `closed`<br>`created`<br>`deleted`<br>`edited`<br>`opened` |
|
664 | | [`org_block`](https://developer.github.com/v3/activity/events/types/#orgblockevent) | `blocked`<br>`unblocked` |
|
665 | | [`organization`](https://developer.github.com/v3/activity/events/types/#organizationevent) | `deleted`<br>`member_added`<br>`member_invited`<br>`member_removed`<br>`renamed` |
|
666 | | [`package`](https://developer.github.com/v3/activity/events/types/#packageevent) | `published`<br>`updated` |
|
667 | | [`page_build`](https://developer.github.com/v3/activity/events/types/#pagebuildevent) | |
|
668 | | [`ping`](https://developer.github.com/v3/activity/events/types/#pingevent) | |
|
669 | | [`project`](https://developer.github.com/v3/activity/events/types/#projectevent) | `closed`<br>`created`<br>`deleted`<br>`edited`<br>`reopened` |
|
670 | | [`project_card`](https://developer.github.com/v3/activity/events/types/#projectcardevent) | `converted`<br>`created`<br>`deleted`<br>`edited`<br>`moved` |
|
671 | | [`project_column`](https://developer.github.com/v3/activity/events/types/#projectcolumnevent) | `created`<br>`deleted`<br>`edited`<br>`moved` |
|
672 | | [`public`](https://developer.github.com/v3/activity/events/types/#publicevent) | |
|
673 | | [`pull_request`](https://developer.github.com/v3/activity/events/types/#pullrequestevent) | `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` |
|
674 | | [`pull_request_review`](https://developer.github.com/v3/activity/events/types/#pullrequestreviewevent) | `dismissed`<br>`edited`<br>`submitted` |
|
675 | | [`pull_request_review_comment`](https://developer.github.com/v3/activity/events/types/#pullrequestreviewcommentevent) | `created`<br>`deleted`<br>`edited` |
|
676 | | [`push`](https://developer.github.com/v3/activity/events/types/#pushevent) | |
|
677 | | [`release`](https://developer.github.com/v3/activity/events/types/#releaseevent) | `created`<br>`deleted`<br>`edited`<br>`prereleased`<br>`published`<br>`released`<br>`unpublished` |
|
678 | | [`repository`](https://developer.github.com/v3/activity/events/types/#repositoryevent) | `archived`<br>`created`<br>`deleted`<br>`edited`<br>`privatized`<br>`publicized`<br>`renamed`<br>`transferred`<br>`unarchived` |
|
679 | | [`repository_dispatch`](https://developer.github.com/v3/activity/events/types/#repositorydispatchevent) | `on-demand-test` |
|
680 | | [`repository_import`](https://developer.github.com/v3/activity/events/types/#repositoryimportevent) | |
|
681 | | [`repository_vulnerability_alert`](https://developer.github.com/v3/activity/events/types/#repositoryvulnerabilityalertevent) | `create`<br>`dismiss`<br>`resolve` |
|
682 | | [`secret_scanning_alert`](https://developer.github.com/v3/activity/events/types/#secretscanningalertevent) | `created`<br>`reopened`<br>`resolved` |
|
683 | | [`security_advisory`](https://developer.github.com/v3/activity/events/types/#securityadvisoryevent) | `performed`<br>`published`<br>`updated`<br>`withdrawn` |
|
684 | | [`sponsorship`](https://developer.github.com/v3/activity/events/types/#sponsorshipevent) | `cancelled`<br>`created`<br>`edited`<br>`pending_cancellation`<br>`pending_tier_change`<br>`tier_changed` |
|
685 | | [`star`](https://developer.github.com/v3/activity/events/types/#starevent) | `created`<br>`deleted` |
|
686 | | [`status`](https://developer.github.com/v3/activity/events/types/#statusevent) | |
|
687 | | [`team`](https://developer.github.com/v3/activity/events/types/#teamevent) | `added_to_repository`<br>`created`<br>`deleted`<br>`edited`<br>`removed_from_repository` |
|
688 | | [`team_add`](https://developer.github.com/v3/activity/events/types/#teamaddevent) | |
|
689 | | [`watch`](https://developer.github.com/v3/activity/events/types/#watchevent) | `started` |
|
690 | | [`workflow_dispatch`](https://developer.github.com/v3/activity/events/types/#workflowdispatchevent) | |
|
691 | | [`workflow_run`](https://developer.github.com/v3/activity/events/types/#workflowrunevent) | `completed`<br>`requested` |
|
692 |
|
693 |
|
694 |
|
695 | ## TypeScript
|
696 |
|
697 | The types for the webhook payloads are sourced from [`@octokit/webhooks-types`](https://github.com/octokit/webhooks/tree/master/payload-types),
|
698 | which can be used by themselves.
|
699 |
|
700 | In addition to these types, `@octokit/webhooks` exports 2 types specific to itself:
|
701 |
|
702 | 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.
|
703 |
|
704 | ### `EmitterWebhookEventName`
|
705 |
|
706 | 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"`.
|
707 |
|
708 | ### `EmitterWebhookEvent`
|
709 |
|
710 | The object that is emitted by `@octokit/webhooks` as an event; made up of an `id`, `name`, and `payload` properties.
|
711 | 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">`.
|
712 |
|
713 | ## License
|
714 |
|
715 | [MIT](LICENSE.md)
|