Skills, MCP and apps / Apps and webhooks
Webhook events and payloads
You write the endpoint that gets the deliveries of a webhook, and anyone can send a POST request to your URL. First check that a request comes from Source, then read its event and parse its fields.
5 min read
Check the signature
Each request has the header X-Source-Signature-256: sha256=<hex>. The hex is the HMAC-SHA256 of the raw request body, with the secret of the webhook as the key. GitHub uses the same scheme.
This receiver checks the signature before it parses the body. It needs Node.js 18 or later, and no packages:
// receiver.mjs
import { createHmac, timingSafeEqual } from 'node:crypto'
import { createServer } from 'node:http'
const secret = process.env.WEBHOOK_SECRET
function isSigned(rawBody, header) {
const expected = Buffer.from(`sha256=${createHmac('sha256', secret).update(rawBody).digest('hex')}`)
const given = Buffer.from(typeof header === 'string' ? header : '')
return given.length === expected.length && timingSafeEqual(given, expected)
}
createServer((req, res) => {
const chunks = []
req.on('data', (chunk) => chunks.push(chunk))
req.on('end', () => {
const rawBody = Buffer.concat(chunks)
if (!isSigned(rawBody, req.headers['x-source-signature-256'])) {
res.writeHead(401).end('bad signature')
return
}
const payload = JSON.parse(rawBody.toString('utf8'))
console.log(req.headers['x-source-event'], payload.action ?? '', req.headers['x-source-delivery'])
res.writeHead(204).end()
})
}).listen(3000)
- Save the code as
receiver.mjs. - Run
WEBHOOK_SECRET=<the secret> node receiver.mjs. - Put the receiver behind an
httpsURL on port 443, for example with a reverse proxy or a tunnel. Use that URL as the webhook URL. - Click Send ping on the webhook. The terminal prints
pingand the delivery id.
The check follows two rules:
- Compute the HMAC over the raw bytes. A body that you parse and serialize again can have other bytes, and its signature does not match.
- Compare with
timingSafeEqual, not with===. A normal compare can tell an attacker how much of a signature is correct.
Headers
| Header | Value |
|---|---|
X-Source-Event | The event name, for example push. |
X-Source-Delivery | The id of the delivery. It is the same on each try of one delivery. |
X-Source-Hook-Id | The id of the webhook. |
X-Source-Signature-256 | sha256= and the hex HMAC-SHA256 of the raw body. |
User-Agent | TanStack-Source-Hookshot |
Content-Type | application/json |
Events and actions
The body has the event in event, and the action in action. ping and push have no action.
| Event | Actions | The subject in the body |
|---|---|---|
ping | none | hook_id |
push | none | push |
issues | opened, edited, closed, reopened, labeled, unlabeled, assigned, unassigned | issue |
pull_request | The actions of issues, and ready_for_review and synchronize (new commits on the head) | pull_request |
issue_comment | created, edited | comment, and issue or pull_request |
pull_request_review | submitted | review and pull_request |
ci_run | started, completed | ci_run |
- A merge sends
pull_requestwith the actionclosed, andmerged: truein the pull request. editedon an issue or a pull request means that its title or its description changed.- A review sends nothing when its text is edited.
completedis sent for a run that ended or was cancelled. A run that was cancelled before it started sendscompletedwith nostarted.
Fields of every body
event: the event name, the same as theX-Source-Eventheader.action: the action, when the event has one.repository:id,owner,name,full_name,urlandprivate.sender: the person who made the change, asidandlogin. It isnullwhen no person made it, for example for aping.truncated:truewhen Source cut a text of the body. It is not there when nothing was cut.
Times, such as merged_at and created_at, are milliseconds since 1970.
Example bodies
ping
{
"event": "ping",
"hook_id": "5b0f2c1e-8d7a-4e4f-9a52-0f3c6d1b2a90",
"repository": {
"id": "8c4e1f7a-2b3d-4c5e-9f60-1a2b3c4d5e6f",
"owner": "acme",
"name": "app",
"full_name": "acme/app",
"url": "https://source.tanstack.com/@acme/app",
"private": false
},
"sender": null
}
The next examples show "repository": { ... } in place of the same object.
push
One push event is sent for each branch or tag that moved, up to 20 for one push. Branches come first, then tags. before is null for a new ref, and after is null for a deleted one. pusher is the same person as sender.
{
"event": "push",
"repository": { ... },
"sender": { "id": "u-ana", "login": "ana" },
"push": {
"ref": "refs/heads/main",
"before": "3f2a9c1d0b8e7f6a5c4d3e2f1a0b9c8d7e6f5a4b",
"after": "9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d",
"created": false,
"deleted": false,
"pusher": { "id": "u-ana", "login": "ana" }
}
}
issues
labels holds the label names. assignees holds the people who have the issue now. login is null when Source does not know the login of a person.
{
"event": "issues",
"action": "labeled",
"repository": { ... },
"sender": { "id": "u-ana", "login": "ana" },
"issue": {
"number": 12,
"title": "Login fails on Safari",
"body": "Steps to reproduce: ...",
"state": "open",
"labels": ["bug"],
"author": { "id": "u-ben", "login": "ben" },
"assignees": [{ "id": "u-ana", "login": "ana" }],
"html_url": "https://source.tanstack.com/@acme/app/issues/12"
}
}
pull_request
A pull request has the fields of an issue, and the fields of the pull request. state is open, closed or merged.
{
"event": "pull_request",
"action": "closed",
"repository": { ... },
"sender": { "id": "u-ana", "login": "ana" },
"pull_request": {
"number": 7,
"title": "Fix the login on Safari",
"body": "Fixes #12",
"state": "merged",
"labels": [],
"author": { "id": "u-ben", "login": "ben" },
"assignees": [],
"html_url": "https://source.tanstack.com/@acme/app/pull/7",
"draft": false,
"merged": true,
"base_ref": "main",
"head_ref": "fix-safari-login",
"head_sha": "9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d",
"merged_at": 1762790400000
}
}
issue_comment
The item of the comment is in issue or in pull_request, by its kind. A comment on a line of a diff has its path and line. replyTo is the id of the comment that it answers.
{
"event": "issue_comment",
"action": "created",
"repository": { ... },
"sender": { "id": "u-ana", "login": "ana" },
"pull_request": { "number": 7, "title": "Fix the login on Safari", "...": "the other fields of a pull request" },
"comment": {
"id": 41,
"body": "This can be null.",
"path": "src/login.ts",
"line": 40,
"replyTo": null
}
}
pull_request_review
state is approved, changes_requested or commented.
{
"event": "pull_request_review",
"action": "submitted",
"repository": { ... },
"sender": { "id": "u-ana", "login": "ana" },
"pull_request": { "number": 7, "title": "Fix the login on Safari", "...": "the other fields of a pull request" },
"review": {
"id": 42,
"state": "approved",
"body": "Looks good."
}
}
ci_run
statusisrunningforstarted, andcompletedorcancelledforcompleted.conclusionissuccess,failure,skipped,cancelled, ornullwhile the run has none.eventis the trigger of the run:push,pull_request,schedule,manual,buttonorafter.trustis the trust level of the run:untrusted,trustedorprotected.
{
"event": "ci_run",
"action": "completed",
"repository": { ... },
"sender": { "id": "u-ana", "login": "ana" },
"ci_run": {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
"workflow": "ci",
"workflow_file": ".source/workflows/ci.ts",
"event": "push",
"ref": "refs/heads/main",
"head_sha": "9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d",
"pull_number": null,
"status": "completed",
"conclusion": "success",
"trust": "protected",
"created_at": 1762790400000,
"finished_at": 1762790520000,
"html_url": "https://source.tanstack.com/@acme/app/ci/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}
}
Retries and timeouts
- A
2xxanswer is a success. Any other status, no answer, or no answer within 10 seconds is a failure. - Source does not follow redirects. A
3xxanswer is a failure. - A delivery has 8 tries: at once, then 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours after Source made it.
- Each try sends the same body, made when the event happened, with the same
X-Source-Delivery. Use that id to skip a delivery that you handled already. A redelivery has a new id. - Deliveries can come out of order, because Source sends some at the same time and retries others later.
So answer fast: send 2xx first, then do the slow work. Source keeps the first 4 KB of your answer in the delivery log.
Long texts
The body of a delivery is at most 64 KB. Source cuts long texts before it sends them:
- The body of an issue, a pull request, a comment or a review: at most 16,000 bytes.
- A title: at most 256 characters.
- The labels and the assignees: at most 100 of each.
A part that was cut has truncated: true, and so does the body. To get the full text, read the item with html_url, or over the REST API.
What is never sent
- An issue or a pull request that screening holds, and its comments and reviews. When screening releases the item, it sends
opened. - A private pull request, and its comments and reviews, until it is public.
- The runs of a hidden workflow.
- A deleted comment.
- A
pushfor a merge done on GitHub in a repository synced with GitHub, and for a branch deleted on the web.
A ci_run event is handed to the webhooks once. If that hand-off fails, the event is lost, and no delivery shows it.