Skip to content
Source
Sign inSign up

Receive app webhooks

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.

EventOn the formWhen
pushPushesA branch or a tag is created, moved or deleted.
issuesIssuesAn issue is opened, edited, closed, reopened, labeled or assigned.
pull_requestPull requestsThe same as issues, and ready for review, new commits (synchronize) and merged.
issue_commentCommentsA comment on an issue or a pull request is created or edited.
pull_request_reviewReviewsA review of a pull request is submitted.
ci_runCI runsA 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:

HeaderValue
X-Source-EventThe event, like pull_request.
X-Source-DeliveryThe id of the delivery. Each try and each redelivery keeps the id, so use it to drop a repeat.
X-Source-Hook-IdThe id of the install.
X-Source-Installation-IdThe id of the install.
X-Source-App-IdThe id of your app.
X-Source-Signature-256sha256=<hex>: the HMAC-SHA256 of the raw body, with your webhook secret as the key.
Content-Typeapplication/json
User-AgentTanStack-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.
  • timingSafeEqual compares 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.id to 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 answerWhat Source does
A 429 or 5xx answer, a timeout, or a host that cannot be reachedTries 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 401Fails 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 installation and app_card with no pick.
  • It checks X-Source-Signature-256 with its webhook secret, and drops repeats by X-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.