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.removeListener()](#webhooksremovelistener)
|
20 | - [webhooks.middleware()](#webhooksmiddleware)
|
21 | - [Webhook events](#webhook-events)
|
22 | - [Special events](#special-events)
|
23 | - [`*` wildcard event](#-wildcard-event)
|
24 | - [`error` event](#error-event)
|
25 | - [TypeScript](#typescript)
|
26 | - [`WebhookEvent`](#webhookevent)
|
27 | - [`EventNames`](#eventnames)
|
28 | - [`EventPayloads`](#eventpayloads)
|
29 | - [License](#license)
|
30 |
|
31 |
|
32 |
|
33 | `@octokit/webhooks` helps to handle webhook events received from GitHub.
|
34 |
|
35 | [GitHub webhooks](https://docs.github.com/webhooks/) can be registered in multiple ways
|
36 |
|
37 | 1. In repository or organization settings on [github.com](https://github.com/).
|
38 | 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/)
|
39 | 3. By [creating a GitHub App](https://docs.github.com/developers/apps/creating-a-github-app).
|
40 |
|
41 | 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.
|
42 |
|
43 | ## Usage
|
44 |
|
45 | ```js
|
46 | // install with: npm install @octokit/webhooks
|
47 | const { Webhooks } = require("@octokit/webhooks");
|
48 | const webhooks = new Webhooks({
|
49 | secret: "mysecret",
|
50 | });
|
51 |
|
52 | webhooks.on("*", ({ id, name, payload }) => {
|
53 | console.log(name, "event received");
|
54 | });
|
55 |
|
56 | require("http").createServer(webhooks.middleware).listen(3000);
|
57 | // can now receive webhook events at port 3000
|
58 | ```
|
59 |
|
60 | ## Local development
|
61 |
|
62 | 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/).
|
63 |
|
64 | Go to [smee.io](https://smee.io/) and <kbd>Start a new channel</kbd>. Then copy the "Webhook Proxy URL" and
|
65 |
|
66 | 1. enter it in the GitHub App’s "Webhook URL" input
|
67 | 2. pass it to the [EventSource](https://github.com/EventSource/eventsource) constructor, see below
|
68 |
|
69 | ```js
|
70 | const webhookProxyUrl = "https://smee.io/IrqK0nopGAOc847"; // replace with your own Webhook Proxy URL
|
71 | const source = new EventSource(webhookProxyUrl);
|
72 | source.onmessage = (event) => {
|
73 | const webhookEvent = JSON.parse(event.data);
|
74 | webhooks
|
75 | .verifyAndReceive({
|
76 | id: webhookEvent["x-request-id"],
|
77 | name: webhookEvent["x-github-event"],
|
78 | signature: webhookEvent["x-hub-signature"],
|
79 | payload: webhookEvent.body,
|
80 | })
|
81 | .catch(console.error);
|
82 | };
|
83 | ```
|
84 |
|
85 | `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')`
|
86 |
|
87 | ## API
|
88 |
|
89 | 1. [Constructor](#constructor)
|
90 | 2. [webhooks.sign()](#webhookssign)
|
91 | 3. [webhooks.verify()](#webhooksverify)
|
92 | 4. [webhooks.verifyAndReceive()](#webhooksverifyandreceive)
|
93 | 5. [webhooks.receive()](#webhooksreceive)
|
94 | 6. [webhooks.on()](#webhookson)
|
95 | 7. [webhooks.removeListener()](#webhooksremoveListener)
|
96 | 8. [webhooks.middleware()](#webhooksmiddleware)
|
97 | 9. [Webhook events](#webhook-events)
|
98 | 10. [Special events](#special-events)
|
99 | 1. [`*` wildcard event](#-wildcard-event)
|
100 | 1. [`error` event](#error-event)
|
101 |
|
102 | ### Constructor
|
103 |
|
104 | ```js
|
105 | new Webhooks({secret[, path, transform]})
|
106 | ```
|
107 |
|
108 | <table width="100%">
|
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 | path
|
125 | </code>
|
126 | <em>(String)</em>
|
127 | </td>
|
128 | <td>
|
129 | Only relevant for <a href="#webhooksmiddleware"><code>webhooks.middleware</code></a>.
|
130 | Custom path to match requests against. Defaults to <code>/</code>.
|
131 | </td>
|
132 | </tr>
|
133 | <tr>
|
134 | <td>
|
135 | <code>
|
136 | transform
|
137 | </code>
|
138 | <em>(Function)</em>
|
139 | </td>
|
140 | <td>
|
141 | Only relevant for <a href="#webhookson"><code>webhooks.on</code></a>.
|
142 | Transform emitted event before calling handlers. Can be asynchronous.
|
143 | </td>
|
144 | </tr>
|
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 | <tr>
|
157 | <td>
|
158 | <code>
|
159 | eventPayload
|
160 | </code>
|
161 | <em>
|
162 | (Object)
|
163 | </em>
|
164 | </td>
|
165 | <td>
|
166 | <strong>Required.</strong>
|
167 | Webhook request payload as received from GitHub
|
168 | </td>
|
169 | </tr>
|
170 | </table>
|
171 |
|
172 | Returns a `signature` string. Throws error if `eventPayload` is not passed.
|
173 |
|
174 | Can also be used [standalone](src/sign/).
|
175 |
|
176 | ### webhooks.verify()
|
177 |
|
178 | ```js
|
179 | webhooks.verify(eventPayload, signature);
|
180 | ```
|
181 |
|
182 | <table width="100%">
|
183 | <tr>
|
184 | <td>
|
185 | <code>
|
186 | eventPayload
|
187 | </code>
|
188 | <em>
|
189 | (Object)
|
190 | </em>
|
191 | </td>
|
192 | <td>
|
193 | <strong>Required.</strong>
|
194 | Webhook event request payload as received from GitHub.
|
195 | </td>
|
196 | </tr>
|
197 | <tr>
|
198 | <td>
|
199 | <code>
|
200 | signature
|
201 | </code>
|
202 | <em>
|
203 | (String)
|
204 | </em>
|
205 | </td>
|
206 | <td>
|
207 | <strong>Required.</strong>
|
208 | Signature string as calculated by <code><a href="#webhookssign">webhooks.sign()</a></code>.
|
209 | </td>
|
210 | </tr>
|
211 | </table>
|
212 |
|
213 | Returns `true` or `false`. Throws error if `eventPayload` or `signature` not passed.
|
214 |
|
215 | Can also be used [standalone](src/verify/).
|
216 |
|
217 | ### webhooks.verifyAndReceive()
|
218 |
|
219 | ```js
|
220 | webhooks.verifyAndReceive({ id, name, payload, signature });
|
221 | ```
|
222 |
|
223 | <table width="100%">
|
224 | <tr>
|
225 | <td>
|
226 | <code>
|
227 | id
|
228 | </code>
|
229 | <em>
|
230 | String
|
231 | </em>
|
232 | </td>
|
233 | <td>
|
234 | Unique webhook event request id
|
235 | </td>
|
236 | </tr>
|
237 | <tr>
|
238 | <td>
|
239 | <code>
|
240 | name
|
241 | </code>
|
242 | <em>
|
243 | String
|
244 | </em>
|
245 | </td>
|
246 | <td>
|
247 | <strong>Required.</strong>
|
248 | 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>
|
249 | in the webhook event request.)
|
250 | </td>
|
251 | </tr>
|
252 | <tr>
|
253 | <td>
|
254 | <code>
|
255 | payload
|
256 | </code>
|
257 | <em>
|
258 | Object
|
259 | </em>
|
260 | </td>
|
261 | <td>
|
262 | <strong>Required.</strong>
|
263 | Webhook event request payload as received from GitHub.
|
264 | </td>
|
265 | </tr>
|
266 | <tr>
|
267 | <td>
|
268 | <code>
|
269 | signature
|
270 | </code>
|
271 | <em>
|
272 | (String)
|
273 | </em>
|
274 | </td>
|
275 | <td>
|
276 | <strong>Required.</strong>
|
277 | Signature string as calculated by <code><a href="#webhookssign">webhooks.sign()</a></code>.
|
278 | </td>
|
279 | </tr>
|
280 | </table>
|
281 |
|
282 | Returns a promise.
|
283 |
|
284 | Verifies event using [webhooks.verify()](#webhooksverify), then handles the event using [webhooks.receive()](#webhooksreceive).
|
285 |
|
286 | Additionally, if verification fails, rejects the returned promise and emits an `error` event.
|
287 |
|
288 | Example
|
289 |
|
290 | ```js
|
291 | const { Webhooks } = require("@octokit/webhooks");
|
292 | const webhooks = new Webhooks({
|
293 | secret: "mysecret",
|
294 | });
|
295 | eventHandler.on("error", handleSignatureVerificationError);
|
296 |
|
297 | // put this inside your webhooks route handler
|
298 | eventHandler
|
299 | .verifyAndReceive({
|
300 | id: request.headers["x-github-delivery"],
|
301 | name: request.headers["x-github-event"],
|
302 | payload: request.body,
|
303 | signature: request.headers["x-hub-signature"],
|
304 | })
|
305 | .catch(handleErrorsFromHooks);
|
306 | ```
|
307 |
|
308 | ### webhooks.receive()
|
309 |
|
310 | ```js
|
311 | webhooks.receive({ id, name, payload });
|
312 | ```
|
313 |
|
314 | <table width="100%">
|
315 | <tr>
|
316 | <td>
|
317 | <code>
|
318 | id
|
319 | </code>
|
320 | <em>
|
321 | String
|
322 | </em>
|
323 | </td>
|
324 | <td>
|
325 | Unique webhook event request id
|
326 | </td>
|
327 | </tr>
|
328 | <tr>
|
329 | <td>
|
330 | <code>
|
331 | name
|
332 | </code>
|
333 | <em>
|
334 | String
|
335 | </em>
|
336 | </td>
|
337 | <td>
|
338 | <strong>Required.</strong>
|
339 | 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>
|
340 | in the webhook event request.)
|
341 | </td>
|
342 | </tr>
|
343 | <tr>
|
344 | <td>
|
345 | <code>
|
346 | payload
|
347 | </code>
|
348 | <em>
|
349 | Object
|
350 | </em>
|
351 | </td>
|
352 | <td>
|
353 | <strong>Required.</strong>
|
354 | Webhook event request payload as received from GitHub.
|
355 | </td>
|
356 | </tr>
|
357 | </table>
|
358 |
|
359 | 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.
|
360 |
|
361 | The `.receive()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
|
362 |
|
363 | ### webhooks.on()
|
364 |
|
365 | ```js
|
366 | webhooks.on(eventName, handler);
|
367 | webhooks.on(eventNames, handler);
|
368 | ```
|
369 |
|
370 | <table width="100%">
|
371 | <tr>
|
372 | <td>
|
373 | <code>
|
374 | eventName
|
375 | </code>
|
376 | <em>
|
377 | String
|
378 | </em>
|
379 | </td>
|
380 | <td>
|
381 | <strong>Required.</strong>
|
382 | Name of the event. One of <a href="https://docs.github.com/developers/webhooks-and-events/webhook-events-and-payloads">GitHub's supported event names</a>.
|
383 | </td>
|
384 | </tr>
|
385 | <tr>
|
386 | <td>
|
387 | <code>
|
388 | eventNames
|
389 | </code>
|
390 | <em>
|
391 | Array
|
392 | </em>
|
393 | </td>
|
394 | <td>
|
395 | <strong>Required.</strong>
|
396 | Array of event names.
|
397 | </td>
|
398 | </tr>
|
399 | <tr>
|
400 | <td>
|
401 | <code>
|
402 | handler
|
403 | </code>
|
404 | <em>
|
405 | Function
|
406 | </em>
|
407 | </td>
|
408 | <td>
|
409 | <strong>Required.</strong>
|
410 | Method to be run each time the event with the passed name is received.
|
411 | the <code>handler</code> function can be an async function, throw an error or
|
412 | return a Promise. The handler is called with an event object: <code>{id, name, payload}</code>.
|
413 | </td>
|
414 | </tr>
|
415 | </table>
|
416 |
|
417 | The `.on()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
|
418 |
|
419 | ### webhooks.removeListener()
|
420 |
|
421 | ```js
|
422 | webhooks.removeListener(eventName, handler);
|
423 | webhooks.removeListener(eventNames, handler);
|
424 | ```
|
425 |
|
426 | <table width="100%">
|
427 | <tr>
|
428 | <td>
|
429 | <code>
|
430 | eventName
|
431 | </code>
|
432 | <em>
|
433 | String
|
434 | </em>
|
435 | </td>
|
436 | <td>
|
437 | <strong>Required.</strong>
|
438 | Name of the event. One of <a href="https://docs.github.com/developers/webhooks-and-events/webhook-events-and-payloads">GitHub’s supported event names</a>.
|
439 | </td>
|
440 | </tr>
|
441 | <tr>
|
442 | <td>
|
443 | <code>
|
444 | eventNames
|
445 | </code>
|
446 | <em>
|
447 | Array
|
448 | </em>
|
449 | </td>
|
450 | <td>
|
451 | <strong>Required.</strong>
|
452 | Array of event names.
|
453 | </td>
|
454 | </tr>
|
455 | <tr>
|
456 | <td>
|
457 | <code>
|
458 | handler
|
459 | </code>
|
460 | <em>
|
461 | Function
|
462 | </em>
|
463 | </td>
|
464 | <td>
|
465 | <strong>Required.</strong>
|
466 | 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.
|
467 | </td>
|
468 | </tr>
|
469 | </table>
|
470 |
|
471 | The `.removeListener()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/).
|
472 |
|
473 | ### webhooks.middleware()
|
474 |
|
475 | ```js
|
476 | webhooks.middleware(request, response[, next])
|
477 | ```
|
478 |
|
479 | <table width="100%">
|
480 | <tr>
|
481 | <td>
|
482 | <code>
|
483 | request
|
484 | </code>
|
485 | <em>
|
486 | Object
|
487 | </em>
|
488 | </td>
|
489 | <td>
|
490 | <strong>Required.</strong>
|
491 | A Node.js <a href="https://nodejs.org/docs/latest/api/http.html#http_class_http_clientrequest">http.ClientRequest</a>.
|
492 | </td>
|
493 | </tr>
|
494 | <tr>
|
495 | <td>
|
496 | <code>
|
497 | response
|
498 | </code>
|
499 | <em>
|
500 | Object
|
501 | </em>
|
502 | </td>
|
503 | <td>
|
504 | <strong>Required.</strong>
|
505 | A Node.js <a href="https://nodejs.org/docs/latest/api/http.html#http_class_http_serverresponse">http.ServerResponse</a>.
|
506 | </td>
|
507 | </tr>
|
508 | <tr>
|
509 | <td>
|
510 | <code>
|
511 | next
|
512 | </code>
|
513 | <em>
|
514 | Function
|
515 | </em>
|
516 | </td>
|
517 | <td>
|
518 | Optional function which invokes the next middleware, as used by <a href="https://github.com/senchalabs/connect">Connect</a> and <a href="http://expressjs.com/">Express</a>.
|
519 | </td>
|
520 | </tr>
|
521 | </table>
|
522 |
|
523 | Returns a `requestListener` (or _middleware_) method which can be directly passed to [`http.createServer()`](https://nodejs.org/docs/latest/api/http.html#http_http_createserver_requestlistener), <a href="http://expressjs.com/">Express</a> and other compatible Node.js server frameworks.
|
524 |
|
525 | Can also be used [standalone](src/middleware/).
|
526 |
|
527 | ### Webhook events
|
528 |
|
529 | See the full list of [event types with example payloads](https://docs.github.com/developers/webhooks-and-events/webhook-events-and-payloads/).
|
530 |
|
531 | 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`.
|
532 |
|
533 | <table ><thead><tr><th class="name-th">Event</th><th class="actions-th">Actions</th></tr></thead><tbody ><tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#checkrunevent"><code>check_run</code></a></td><td class="actions-td td_text"><code>completed</code><br><code>created</code><br><code>requested_action</code><br><code>rerequested</code></td></tr>
|
534 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#checksuiteevent"><code>check_suite</code></a></td><td class="actions-td td_text"><code>completed</code><br><code>requested</code><br><code>rerequested</code></td></tr>
|
535 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#codescanningalertevent"><code>code_scanning_alert</code></a></td><td class="actions-td td_text"><code>appeared_in_branch</code><br><code>closed_by_user</code><br><code>created</code><br><code>fixed</code><br><code>reopened</code><br><code>reopened_by_user</code></td></tr>
|
536 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#commitcommentevent"><code>commit_comment</code></a></td><td class="actions-td td_text"><code>created</code></td></tr>
|
537 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#contentreferenceevent"><code>content_reference</code></a></td><td class="actions-td td_text"><code>created</code></td></tr>
|
538 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#createevent"><code>create</code></a></td><td class="actions-td td_num"></td></tr>
|
539 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#deleteevent"><code>delete</code></a></td><td class="actions-td td_num"></td></tr>
|
540 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#deploykeyevent"><code>deploy_key</code></a></td><td class="actions-td td_text"><code>created</code><br><code>deleted</code></td></tr>
|
541 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#deploymentevent"><code>deployment</code></a></td><td class="actions-td td_text"><code>created</code></td></tr>
|
542 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#deploymentstatusevent"><code>deployment_status</code></a></td><td class="actions-td td_text"><code>created</code></td></tr>
|
543 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#forkevent"><code>fork</code></a></td><td class="actions-td td_num"></td></tr>
|
544 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#githubappauthorizationevent"><code>github_app_authorization</code></a></td><td class="actions-td td_text"><code>revoked</code></td></tr>
|
545 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#gollumevent"><code>gollum</code></a></td><td class="actions-td td_num"></td></tr>
|
546 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#installationevent"><code>installation</code></a></td><td class="actions-td td_text"><code>created</code><br><code>deleted</code><br><code>new_permissions_accepted</code><br><code>suspend</code><br><code>unsuspend</code></td></tr>
|
547 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#installationrepositoriesevent"><code>installation_repositories</code></a></td><td class="actions-td td_text"><code>added</code><br><code>removed</code></td></tr>
|
548 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#issuecommentevent"><code>issue_comment</code></a></td><td class="actions-td td_text"><code>created</code><br><code>deleted</code><br><code>edited</code></td></tr>
|
549 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#issuesevent"><code>issues</code></a></td><td class="actions-td td_text"><code>assigned</code><br><code>closed</code><br><code>deleted</code><br><code>demilestoned</code><br><code>edited</code><br><code>labeled</code><br><code>locked</code><br><code>milestoned</code><br><code>opened</code><br><code>pinned</code><br><code>reopened</code><br><code>transferred</code><br><code>unassigned</code><br><code>unlabeled</code><br><code>unlocked</code><br><code>unpinned</code></td></tr>
|
550 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#labelevent"><code>label</code></a></td><td class="actions-td td_text"><code>created</code><br><code>deleted</code><br><code>edited</code></td></tr>
|
551 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#marketplacepurchaseevent"><code>marketplace_purchase</code></a></td><td class="actions-td td_text"><code>cancelled</code><br><code>changed</code><br><code>pending_change</code><br><code>pending_change_cancelled</code><br><code>purchased</code></td></tr>
|
552 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#memberevent"><code>member</code></a></td><td class="actions-td td_text"><code>added</code><br><code>edited</code><br><code>removed</code></td></tr>
|
553 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#membershipevent"><code>membership</code></a></td><td class="actions-td td_text"><code>added</code><br><code>removed</code></td></tr>
|
554 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#metaevent"><code>meta</code></a></td><td class="actions-td td_text"><code>deleted</code></td></tr>
|
555 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#milestoneevent"><code>milestone</code></a></td><td class="actions-td td_text"><code>closed</code><br><code>created</code><br><code>deleted</code><br><code>edited</code><br><code>opened</code></td></tr>
|
556 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#organizationevent"><code>organization</code></a></td><td class="actions-td td_text"><code>deleted</code><br><code>member_added</code><br><code>member_invited</code><br><code>member_removed</code><br><code>renamed</code></td></tr>
|
557 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#orgblockevent"><code>org_block</code></a></td><td class="actions-td td_text"><code>blocked</code><br><code>unblocked</code></td></tr>
|
558 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#packageevent"><code>package</code></a></td><td class="actions-td td_text"><code>published</code><br><code>updated</code></td></tr>
|
559 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#pagebuildevent"><code>page_build</code></a></td><td class="actions-td td_num"></td></tr>
|
560 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#pingevent"><code>ping</code></a></td><td class="actions-td td_num"></td></tr>
|
561 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#projectcardevent"><code>project_card</code></a></td><td class="actions-td td_text"><code>converted</code><br><code>created</code><br><code>deleted</code><br><code>edited</code><br><code>moved</code></td></tr>
|
562 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#projectcolumnevent"><code>project_column</code></a></td><td class="actions-td td_text"><code>created</code><br><code>deleted</code><br><code>edited</code><br><code>moved</code></td></tr>
|
563 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#projectevent"><code>project</code></a></td><td class="actions-td td_text"><code>closed</code><br><code>created</code><br><code>deleted</code><br><code>edited</code><br><code>reopened</code></td></tr>
|
564 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#publicevent"><code>public</code></a></td><td class="actions-td td_num"></td></tr>
|
565 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#pullrequestevent"><code>pull_request</code></a></td><td class="actions-td td_text"><code>assigned</code><br><code>closed</code><br><code>edited</code><br><code>labeled</code><br><code>locked</code><br><code>merged</code><br><code>opened</code><br><code>ready_for_review</code><br><code>reopened</code><br><code>review_request_removed</code><br><code>review_requested</code><br><code>synchronize</code><br><code>unassigned</code><br><code>unlabeled</code><br><code>unlocked</code></td></tr>
|
566 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#pullrequestreviewevent"><code>pull_request_review</code></a></td><td class="actions-td td_text"><code>dismissed</code><br><code>edited</code><br><code>submitted</code></td></tr>
|
567 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#pullrequestreviewcommentevent"><code>pull_request_review_comment</code></a></td><td class="actions-td td_text"><code>created</code><br><code>deleted</code><br><code>edited</code></td></tr>
|
568 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#pushevent"><code>push</code></a></td><td class="actions-td td_num"></td></tr>
|
569 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#releaseevent"><code>release</code></a></td><td class="actions-td td_text"><code>created</code><br><code>deleted</code><br><code>edited</code><br><code>prereleased</code><br><code>published</code><br><code>released</code><br><code>unpublished</code></td></tr>
|
570 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#repositorydispatchevent"><code>repository_dispatch</code></a></td><td class="actions-td td_text"><code>on-demand-test</code></td></tr>
|
571 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#repositoryevent"><code>repository</code></a></td><td class="actions-td td_text"><code>archived</code><br><code>created</code><br><code>deleted</code><br><code>edited</code><br><code>privatized</code><br><code>publicized</code><br><code>renamed</code><br><code>transferred</code><br><code>unarchived</code></td></tr>
|
572 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#repositoryimportevent"><code>repository_import</code></a></td><td class="actions-td td_num"></td></tr>
|
573 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#repositoryvulnerabilityalertevent"><code>repository_vulnerability_alert</code></a></td><td class="actions-td td_text"><code>create</code><br><code>dismiss</code><br><code>resolve</code></td></tr>
|
574 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#secretscanningalertevent"><code>secret_scanning_alert</code></a></td><td class="actions-td td_text"><code>created</code><br><code>reopened</code><br><code>resolved</code></td></tr>
|
575 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#securityadvisoryevent"><code>security_advisory</code></a></td><td class="actions-td td_text"><code>performed</code><br><code>published</code><br><code>updated</code></td></tr>
|
576 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#sponsorshipevent"><code>sponsorship</code></a></td><td class="actions-td td_text"><code>cancelled</code><br><code>created</code><br><code>edited</code><br><code>pending_cancellation</code><br><code>pending_tier_change</code><br><code>tier_changed</code></td></tr>
|
577 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#starevent"><code>star</code></a></td><td class="actions-td td_text"><code>created</code><br><code>deleted</code></td></tr>
|
578 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#statusevent"><code>status</code></a></td><td class="actions-td td_num"></td></tr>
|
579 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#teamevent"><code>team</code></a></td><td class="actions-td td_text"><code>added_to_repository</code><br><code>created</code><br><code>deleted</code><br><code>edited</code><br><code>removed_from_repository</code></td></tr>
|
580 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#teamaddevent"><code>team_add</code></a></td><td class="actions-td td_num"></td></tr>
|
581 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#watchevent"><code>watch</code></a></td><td class="actions-td td_text"><code>started</code></td></tr>
|
582 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#workflowdispatchevent"><code>workflow_dispatch</code></a></td><td class="actions-td td_num"></td></tr>
|
583 | <tr ><td class="name-td td_text"><a href="https://developer.github.com/v3/activity/events/types/#workflowrunevent"><code>workflow_run</code></a></td><td class="actions-td td_text"><code>action</code><br><code>completed</code><br><code>requested</code></td></tr></tbody></table>
|
584 |
|
585 | ### Special events
|
586 |
|
587 | Besides the webhook events, there are [special events](#specialevents) emitted by `@octokit/webhooks`.
|
588 |
|
589 | #### `*` wildcard event
|
590 |
|
591 | The `*` event is emitted for all webhook events [listed above](#listofwebhookevents).
|
592 |
|
593 | ```js
|
594 | webhooks.on("*", (event) => {
|
595 | console.log(`"${event.name}" event received"`);
|
596 | });
|
597 | ```
|
598 |
|
599 | #### `error` event
|
600 |
|
601 | If a webhook event handler throws an error or returns a promise that rejects, an `error` event is triggered. You can subscribe to this event for logging or reporting events. The passed `error` object has a `.event` property which has all information on the event:
|
602 |
|
603 | - `id`: The unique webhook event request id
|
604 | - `name`: The name of the event
|
605 | - `payload`: The event request payload
|
606 |
|
607 | ```js
|
608 | webhooks.on("error", (error) => {
|
609 | console.log(`Error occured in "${error.event.name} handler: ${error.stack}"`);
|
610 | });
|
611 | ```
|
612 |
|
613 | Asynchronous `error` event handler are not blocking the `.receive()` method from completing.
|
614 |
|
615 | ## TypeScript
|
616 |
|
617 | `@octokit/webhooks` exports 3 types that can be used independent from the code.
|
618 |
|
619 | 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.
|
620 |
|
621 | ### `WebhookEvent`
|
622 |
|
623 | The `WebhookEvent` type is an object with the properties `id`, `name`, and `payload`. `name` must be one of the known event names. The type for `payload` be set using an optional type parameter, e.g. `WebhookEvent<MyPayloadType>`
|
624 |
|
625 | ### `EventNames`
|
626 |
|
627 | The `EventNames` type is a module containing types for all known event names and event/action combinations. For example, `EventNames.CheckRunEvent` is a string enum for `"check_run" | "check_run.completed" | "check_run.created" | "check_run.requested_action" | "check_run.rerequested"`.
|
628 |
|
629 | `EventNames.All` is an enum of all event/action combinations. `EventNames.StringNames` is an enum for the known event names only.
|
630 |
|
631 | ### `EventPayloads`
|
632 |
|
633 | The `EventPayloads` type exports payload types for all known evens. For example `EventPayloads.WebhookPayloadCheckRun` exports the payload type for the `check_run` event.
|
634 |
|
635 | ## License
|
636 |
|
637 | [MIT](LICENSE.md)
|