-
Notifications
You must be signed in to change notification settings - Fork 16
/
github_webhooks.saas.txt
422 lines (350 loc) · 21.1 KB
/
github_webhooks.saas.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
GITHUB_WEBHOOKS
GITHUB MAIN|API|CLI|APPS
|ACTIONS ==> #See other GitHub docs
SUMMARY ==> #Types: GitHub app, REPO, ORG
#Calls: events, subevents, payloads, JSON|urlencoded, secret|authentication
#Deliveries: list, ping, repeat push, retry
#Settings: disable, HTTPS
#Client: Octokit, Node middleware
/=+===============================+=\
/ : : \
)==: MAIN :==(
\ :_______________________________: /
\=+===============================+=/
WEBHOOK TYPES ==> #Webhooks can be for a:
# - GitHub app
# - REPO: UI or API
# - ORG: UI or API
OORG/hooks[/...] #Same as RREPO/hooks[/...] but with ORG webhooks
#No .../test endpoint
/app/hook[/...] #Same as RREPO/hooks/WEBHOOK_ID[/...] but with GitHub app webhooks
#Must be authenticated with an APP_JWT
#Only for .../config|deliveries endpoints
POST RREPO/hooks #
GET RREPO/hooks #
XWEBHOOK.url
GET RREPO/hooks/WEBHOOK_ID #
PATCH RREPO/hooks/WEBHOOK_ID #
DELETE RREPO/hooks/WEBHOOK_ID #
XWEBHOOK.id #XWEBHOOK_ID
XWEBHOOK_C.name #Always 'web'
XWEBHOOK.type #'Repository|Organization'
XWEBHOOK_U.active #BOOL. To disable
XWEBHOOK_U.events #'EVENT'_UARR
XWEBHOOK_U.config #XWEBHOOK_CONF_C|F
XWEBHOOK.last_response.code #NUM|null. HTTP status
XWEBHOOK.last_response.status #STR|null
XWEBHOOK.last_response.message #STR|null
XWEBHOOK.created_at|updated_at #'DATE'
GET RREPO/hooks/WEBHOOK_ID/config #
PATCH
RREPO /hooks/WEBHOOK_ID/config #
XWEBHOOK_CONF_U.url #'WEBHOOK_URL' to send requests to
XWEBHOOK_CONF_U.token #STR
XWEBHOOK_CONF_U.digest #Always 'sha256'
XWEBHOOK_CONF_U.room #STR
XWEBHOOK_CONF_F.email #'EMAIL'
XWEBHOOK_CONF_F.username #STR
XWEBHOOK_CONF_F.password #STR
XWEBHOOK_CONF_F.subdomain #STR
/=+===============================+=\
/ : : \
)==: CALL :==(
\ :_______________________________: /
\=+===============================+=/
POST WEBHOOK_URL #
XWEBHOOK_CONF_U.insecure_ssl #'0|1'. If '0', require HTTPS
XWEBHOOK_CONF_U.content_type #Whether Content-Type [C] is 'json' (application/json) or 'form' (application/x-www-form-urlencoded)
WEVENT.name
X-GitHub-Event: EVENT [C] #
WEVENT.id
X-GitHub-Delivery: EVENT_ID [C] #
User-Agent:
GitHub-Hookshot/ID [C] #
WEVENT.payload #Passed to webhook
PAYLOAD #Max 25MB
PAYLOAD.action #'SUBEVENT'
PAYLOAD.sender #USER that triggered the event
PAYLOAD.repository #REPO
PAYLOAD.organization #ORG
PAYLOAD.* #EVENT|SUBEVENT-specific
/=+===============================+=\
/ : : \
)==: AUTHENTICATION :==(
\ :_______________________________: /
\=+===============================+=/
XWEBHOOK_CONF_U.secret
WOPTS.secret #Webhook-specific, private
WEBHOOK_SECRET #Any XWEBHOOK (not XWEBHOOK_CONF) update deletes it unless specified
WEVENT.signature
X-GitHub-Signature-256: #SHA256_HMAC(PAYLOAD, WEBHOOK_SECRET)
sha256=HASH [C] #Used for authentication|integration
@octokit/webhooks
sign|verify(...) #Forwards to @octokit/webhook-methods
WHOOKS.sign|verify(...) #Forwards to @octokit/webhook-methods, but without 'WEBHOOK_SECRET' argument
@octokit/webhooks-methods #Version 4.0.0
#Node/Deno
#Browsers too, but WEBHOOK_SECRET should not be exposed to client code
sign('WEBHOOK_SECRET', 'PAYLOAD')
->>'HASH' #
verify('WEBHOOK_SECRET',
'PAYLOAD', 'HASH')->>BOOL #
verifyWithFallback
(..., 'WEBHOOK_SECRET'_ARR)
->>BOOL #Like verify() but with multiple WEBHOOK_SECRETs (for rotated keys)
/=+===============================+=\
/ : : \
)==: DELIVERY :==(
\ :_______________________________: /
\=+===============================+=/
XWEBHOOK.deliveries_url
GET
RREPO/hooks/WEBHOOK_ID/deliveries#
GET RREPO/hooks/WEBHOOK_ID
/deliveries/DELIVERY_ID #
XWEBHOOK_DELIVERY #Webhook call
XWEBHOOK_DELIVERY.id #DELIVERY_ID
XWEBHOOK_DELIVERY.guid #'EVENT_ID'
XWEBHOOK_DELIVERY.event #'EVENT'
XWEBHOOK_DELIVERY.action #'SUBEVENT'|null
XWEBHOOK_DELIVERY.repository_id #REPO_ID|null
XWEBHOOK_DELIVERY.status #STR. HTTP status
XWEBHOOK_DELIVERY.status_code #NUM
XWEBHOOK_DELIVERY.duration #NUM
XWEBHOOK_DELIVERY.delivered_at #'DATE'
?redelivery
XWEBHOOK_DELIVERY.redelivery #BOOL. Whether it was retried
XWEBHOOK_DELIVERY_F
.request.headers #OBJ|null
XWEBHOOK_DELIVERY_F
.request.payload #OBJ|null
XWEBHOOK_DELIVERY_F
.response.headers #OBJ|null
XWEBHOOK_DELIVERY_F
.response.payload #STR|null
POST RREPO/hooks/WEBHOOK_ID
/deliveries/DELIVERY_ID/attempts #Retry. Empty REQ|RES
XWEBHOOK.ping_url
PATCH RREPO/hooks/WEBHOOK_ID/pings#Trigger a 'ping' EVENT. Empty REQ|RES
XWEBHOOK.test_url
PATCH RREPO /hooks/WEBHOOK_ID/test#Repeat last 'push' EVENT. Empty REQ|RES
/=+===============================+=\
/ : : \
)==: EVENTS :==(
\ :_______________________________: /
\=+===============================+=/
EVENT #Webhook main event
#Max 20 WEBHOOKs per EVENT
SUBEVENT #Webhook sub-event. Also named "action"
* #Any EVENT
ping #Webhook creation
#Can also be triggered with POST RREPO/hooks/WEBHOOK_ID/pings
meta #Webhook itself
#SUBEVENTs: deleted
repository_dispatch #Custom event, triggered by POST RREPO/dispatches
#SUBEVENTs: 'CUSTOM'
repository #SUBEVENTs:
# - created edited deleted [un]archived
# - privatized publicized
# - renamed transferred
repository_import #Import REPO from another VCS
create|delete #A branch|tag
public #Make private repository public
branch_protection_rule #Branch protection rule changed.
#SUBEVENTs: created|edited|deleted
watch #REPO star (not when starting watching)
#SUBEVENTs: started
star #REPO star
#SUBEVENTs: created deleted
fork #Someone forked repo
push #New commit.
#Includes push to a branch that is also a pull request (i.e. would create 2 workflows, one
#for push, one for pull_request)
#Does not include push to a forked repository that is also a pull_request
commit_comment #Comment on a commit
pull_request #SUBEVENTs (def: opened synchronize reopened):
# - [re]opened edited closed
# - [un]locked
# - [un]assigned
# - [un]labeled
# - synchronize
# - converted_to_draft ready_for_review review_requested review_request_removed
# - automerge_enabled|disabled
# - dequeued|enqueued merged
pull_request_review #SUBEVENTs: submitted edited dismissed
pull_request_review_thread #SUBEVENTs: [un]resolved
pull_request_review_comment #SUBEVENTs: created edited deleted
merge_group #PR added to a merge queue
#SUBEVENTs: checks_requested
issues #SUBEVENTs:
# - [re]opened edited deleted closed
# - [un]locked
# - [un]pinned
# - [un]assigned
# - [un]labeled
# - [de]milestoned
# - transferred (to another repo)
issue_comment #Each comment in an issue|PR
#SUBEVENTs: created edited deleted
discussion #SUBEVENTs:
# - created edited deleted
# - [un]locked
# - [un]pinned
# - [un]labeled
# - [un]answered
# - transferred (to another repo)
# - category_changed
discussion_comment #Each comment in a discussion
#SUBEVENTs: created edited deleted
label #List of possible issue labels in the repository
#SUBEVENTs: created edited deleted
milestone #SUBEVENTs: created opened edited deleted closed
project #GitHub project
#SUBEVENTs: created|reopened edited deleted closed
project_column #GitHub project column of cards
#SUBEVENTs: created edited deleted moved
project_card #GitHub project card
#SUBEVENTs: created edited deleted moved converted (to an issue)
projects_v2 #GitHub project, ORG-level
#SUBEVENTs: created|reopened edited deleted closed
projects_v2_item #GitHub project item, ORG-level
#SUBEVENTs: created|restored edited deleted archived converted reordered
release #GitHub release
#SUBEVENTs: created edited deleted [pre]released|[un]published
registry_package #SUBEVENTs: published updated
deployment #Deploy code to remote server
#Must be handled by external providers
#SUBEVENTs: created
deployment_status #Deployment status changed
#SUBEVENTs: created
deploy_key #SUBEVENTs: created deleted
status #Commit status
check_suite #Group of checks (automatic CI actions)
#SUBEVENTs: [re]requested completed
check_run #Single check
#SUBEVENTs: created|rerequested completed requested_action (button to ask user for additional action)
code_scanning_alert #SUBEVENTs:
# - created fixed
# - appeared_in_branch (already created but appeared in a new branch)
# - reopened (not manually by user)
# - reopened|closed_by_user
repository_vulnerability_alert #Security vulnerability.
#SUBEVENTs: create dismiss resolve
dependabot_alert #SUBEVENTs:
# - created dismissed fixed
# - reintroduced reopened
security_advisory #Security in GitHub itself.
#SUBEVENTs: published updated withdrawn performed
organization #SUBEVENTs:
# - renamed deleted
# - member_invited|added|removed
org_block #SUBEVENTs: [un]blocked
membership #ORG members
#SUBEVENTs: added removed
team #ORG team
#SUBEVENTs:
# - created edited deleted
# - added_to_repository removed_from_repository
team_add #ORG team added to a REPO
member #Repo collaborators|admins
#SUBEVENTs: added edited deleted
sponsorship #SUBEVENTs:
# - created edited
# - pending_cancellation cancelled
# - pending_tier_change tier_changed
page_build #GitHub Pages build
gollum #Wiki update
workflow_dispatch #UI button trigger
workflow_run #Run of another WORKFLOW
#SUBEVENTs: requested in_progress completed
#OPTS:
# - workflows 'WORKFLOW'_ARR
workflow_job #Run of a WORKFLOW JOB
#SUBEVENTs: queued waiting (for approval) in_progress completed
github_app_authorization
installation
installation_repositories
installation_target
marketplace_purchase #See GitHub app doc
@octokit/webhooks-examples|schemas#Version 7.0.3
#Node/Deno/browsers
#List of webhook events definitions
#JSON schema:
# - v7
# - requires ajv-formats, and ajv.addKeyword('tsAdditionalProperties')
@octokit/webhooks-examples #WEBHOOK_EXAMPLES_ARR
WEBHOOK_EXAMPLES.name #'EVENT'
WEBHOOK_EXAMPLES.actions #'SUBEVENT'_ARR
WEBHOOK_EXAMPLES.properties.PROP #JSON_SCHEMA_OBJ of PAYLOAD.PROP
WEBHOOK_EXAMPLES.description #STR
WEBHOOK_EXAMPLES.examples #PAYLOAD_ARR
@octokit/webhooks-schemas #JSON_SCHEMA_OBJ of any PAYLOAD (using `oneOf`)
@octokit/webhooks
emitterEventNames #'EVENT[.SUBEVENT]'_ARR
/=+===============================+=\
/ : : \
)==: LISTENER :==(
\ :_______________________________: /
\=+===============================+=/
@octokit/webhooks #12.0.3
#Node
#Deno, except createNodeMiddleware()
#Browsers too, but WEBHOOK_SECRET should not be exposed to client code
new Webhooks(WOPTS) #WHOOKS
createEventHandler([EOPTS])
->WHANDLER #
WHOOKS.verifyAndReceive(WEVENT)->>#Does verify() + receive()
#WEVENT.payload must be JSON stringified
WOPTS|EOPTS|NOPTS.log #LOGS_OBJ
#Used for:
# - error: error event
# - warn: unknown 'EVENT[.SUBEVENT]'
# - debug: new WEVENT (EVENT + EVENT_ID) with Node middleware
WOPTS|EOPTS.transform #FUNC(WEVENT)->WEVENT mapping it for event listeners
WHOOKS|WHANDLER.on
('EVENT[.SUBEVENT]'[_ARR],
FUNC(WEVENT)[->>]) #Add event listener
WHOOKS|WHANDLER
.onAny(FUNC(WEVENT)[->>]) #
WHOOKS|WHANDLER.removeListener
('*|EVENT[.SUBEVENT]'[_ARR]) #Remove event listener
WHOOKS|WHANDLER #Trigger event listener
.receive(WEVENT)->> #Propagates errors
WHOOKS|WHANDLERa #When:
.onError(FUNC(ERROR)) # - an event handler throws
# - verifyAndReceive() has WEVENT with invalid signature
# - ERROR.status 400
ERROR.name #'AggregateError'
ERROR.errors #ERROR2_ARR
ERROR2.event #'EVENT' of FUNC that threw
ERROR.event #'EVENT' of WHANDLER.receive(WEVENT)
/=+===============================+=\
/ : : \
)==: MIDDLEWARE :==(
\ :_______________________________: /
\=+===============================+=/
@octokit/webhooks #
createNodeMiddleware #Express-style middleware
(WHOOKS[, NOPTS]) #Calls WHOOKS.verifyAndReceive(WEVENT)
->FUNC(REQ, RES, FUNC2) #Then calls RES.end('ok\n')
->>BOOL #Uses REQ.url:
# - to check if NOPTS.path matches
# - skipped, and return false if not
#Uses REQ.headers
# - to set WEVENT.id|name|signature
# - Using X-GitHub-Event [C], X-Hub-Signature-256 [C], X-GitHub-Delivery [C]
#Uses request body:
# - either REQ.body STR, or REQ ISTREAM
# - to set WEVENT.payload
#Errors:
# - JSON, as OBJ: error 'ERROR'
# - 400: no X-GitHub-Event [C], X-Hub-Signature-256 [C], X-GitHub-Delivery [C]
# - 400: request payload invalid JSON
# - 404: not POST
# - 415: not Content-Type: application/json [C]
# - 422: invalid REQ.url
# - 500: event listener error
#Sends 202 every 9s to prevent GitHub from closing request
NOPTS.path #'/PATH' (def: '/api/github/webhooks')