Skills, MCP and apps / Apps and webhooks
Receive webhooks in your app
Your app must react to a push, a new pull request or a comment on a repository where it is installed. Asking the API again and again is slow, and it costs you install tokens.
5 min read
Source sends your app a webhook: a signed JSON POST to your webhook URL, one for each event that your app picked. An app webhook is a repository webhook with one more field: installation.
1. Pick the events
On /settings/apps/<slug>, set the Webhook URL (https, a public host), and pick the Events. Then save.
Each install gets the events that its account approved. To learn what happens when you add events later, see Approve a permission request.
| Event | On the form | When |
|---|---|---|
push | Pushes | A branch or a tag is created, moved or deleted. |
issues | Issues | An issue is opened, edited, closed, reopened, labeled or assigned. |
pull_request | Pull requests | The same as issues, and ready for review, new commits (synchronize) and merged. |
issue_comment | Comments | A comment on an issue or a pull request is created or edited. |
pull_request_review | Reviews | A review of a pull request is submitted. |
ci_run | CI runs | A CI run starts or ends. |
The actions of each event are in Events and actions.
Every app also gets two events that it does not pick:
installation: an account installed the app, changed the install, or uninstalled it.app_card: a person clicked a webhook button of the card of your app.
2. Check the signature
Each webhook has these headers:
| Header | Value |
|---|---|
X-Source-Event | The event, like pull_request. |
X-Source-Delivery | The id of the delivery. Each try and each redelivery keeps the id, so use it to drop a repeat. |
X-Source-Hook-Id | The id of the install. |
X-Source-Installation-Id | The id of the install. |
X-Source-App-Id | The id of your app. |
X-Source-Signature-256 | sha256=<hex>: the HMAC-SHA256 of the raw body, with your webhook secret as the key. |
Content-Type | application/json |
User-Agent | TanStack-Source-Hookshot |
Check the signature against the raw body, before you parse it. This check runs in Node.js 18 or later:
import { createHmac, timingSafeEqual } from 'node:crypto'
function isSigned(secret, rawBody, header) {
const expected = Buffer.from(createHmac('sha256', secret).update(rawBody).digest('hex'))
const given = Buffer.from(typeof header === 'string' ? header.replace(/^sha256=/, '') : '')
return given.length === expected.length && timingSafeEqual(given, expected)
}
// isSigned(process.env.WEBHOOK_SECRET, rawBody, req.headers['x-source-signature-256'])
- Compute the HMAC over the raw bytes. A body that you parse and serialize again can have other bytes.
timingSafeEqualcompares in constant time. A normal compare can tell an attacker how much of a signature is correct.
For a Cloudflare Worker, see the isSigned function in Build an app.
3. Read the body
Repository events
The body of a repository event is the body that a repository webhook gets, with installation added:
{
"event": "pull_request",
"action": "opened",
"repository": {
"id": "8c1e4b7a2f9d0635",
"owner": "alice",
"name": "app",
"full_name": "alice/app",
"url": "https://source.tanstack.com/@alice/app",
"private": false
},
"sender": { "id": "3a7c91e04b2d8f56", "login": "bob" },
"pull_request": {
"number": 7,
"title": "Add dark mode",
"state": "open",
"html_url": "https://source.tanstack.com/@alice/app/pull/7",
"base_ref": "main",
"head_ref": "dark-mode",
"head_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8",
"...": "the other fields of a pull request"
},
"installation": { "id": "5d2a9e0c71b84f36" }
}
- Use
repository.full_name(owner/name) in REST paths. - Use
installation.idto get an install token for the event. - Each field of each event is in Example bodies.
installation
action is created, changed or deleted. changed comes when a repository joins or leaves the install, and when the account approves new permissions or events. The body holds the install as it is now, or as it was for deleted:
{
"event": "installation",
"action": "created",
"installation": {
"id": "5d2a9e0c71b84f36",
"app_id": "1f0e7d3c9b2a4856",
"account": { "id": "6b4d2f8a0c1e3957", "login": "alice" },
"repositories": [{ "id": "8c1e4b7a2f9d0635", "full_name": "alice/app" }],
"permissions": ["pulls:read", "surfaces:write"],
"events": ["pull_request"]
},
"sender": { "id": "6b4d2f8a0c1e3957", "login": "alice" }
}
repositories is "all" for an install on all the repositories of the account.
app_card
action is clicked. button.id is the id that you gave the button. See Cards and statuses.
{
"event": "app_card",
"action": "clicked",
"repository": { "...": "the same as above" },
"pull_request": { "number": 7, "html_url": "https://source.tanstack.com/@alice/app/pull/7" },
"button": { "id": "rebuild" },
"sender": { "id": "3a7c91e04b2d8f56", "login": "bob" },
"installation": { "id": "5d2a9e0c71b84f36" }
}
Note
No webhook carries held or hidden content, or a run of a hidden workflow. See What is never sent.
4. Answer fast
Answer with a 2xx status within 10 seconds. Then the delivery counts as delivered.
| Your answer | What Source does |
|---|---|
A 429 or 5xx answer, a timeout, or a host that cannot be reached | Tries again for about one day. The first wait is 30 seconds. Each wait is two times the last, up to one hour. |
Any other answer, like 400 or 401 | Fails the delivery, with no retry. |
A redirect (3xx) | Fails the delivery, with no retry. Source does not follow a redirect. |
A body over 256 KB is not sent: the delivery fails with payload too large.
Note
An app gets at most 5,000 webhooks an hour, and at most 50 at the same time. More wait for later.
What works now
- Your app gets a signed webhook for each event that it picked, with the body of a repository webhook and its
installation. - It gets
installationandapp_cardwith no pick. - It checks
X-Source-Signature-256with its webhook secret, and drops repeats byX-Source-Delivery. - Failed deliveries retry for about a day, and you can send any delivery again from the log.
Read the delivery log
The app keeps its newest 500 deliveries. Open /settings/apps/<slug>, and find Deliveries. Each row shows:
- the event and the time,
- the status: pending, delivered or failed,
- the number of tries, and the last answer or error.
To send a delivery again now, with a new day of retries, click Redeliver on a delivered or failed row.
The server of your app can do the same with its app secret:
curl https://source.tanstack.com/api/v1/app/deliveries \
-H "Authorization: Bearer $APP_SECRET"
curl -X POST https://source.tanstack.com/api/v1/app/deliveries/<id>/redeliver \
-H "Authorization: Bearer $APP_SECRET"
The list gives the newest 100, each with the first 2,048 characters of its body.
When a webhook does not come
Source checks the install again before it keeps each event. It drops the event when:
- the app is suspended, or has no webhook URL,
- the install is gone, or did not approve the event,
- the repository left the install, or moved to another account.
Dropped events are not in the delivery log.