Skip to content
Source
Sign inSign up

Webhook events and payloads

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)
  1. Save the code as receiver.mjs.
  2. Run WEBHOOK_SECRET=<the secret> node receiver.mjs.
  3. Put the receiver behind an https URL on port 443, for example with a reverse proxy or a tunnel. Use that URL as the webhook URL.
  4. Click Send ping on the webhook. The terminal prints ping and 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

HeaderValue
X-Source-EventThe event name, for example push.
X-Source-DeliveryThe id of the delivery. It is the same on each try of one delivery.
X-Source-Hook-IdThe id of the webhook.
X-Source-Signature-256sha256= and the hex HMAC-SHA256 of the raw body.
User-AgentTanStack-Source-Hookshot
Content-Typeapplication/json

Events and actions

The body has the event in event, and the action in action. ping and push have no action.

EventActionsThe subject in the body
pingnonehook_id
pushnonepush
issuesopened, edited, closed, reopened, labeled, unlabeled, assigned, unassignedissue
pull_requestThe actions of issues, and ready_for_review and synchronize (new commits on the head)pull_request
issue_commentcreated, editedcomment, and issue or pull_request
pull_request_reviewsubmittedreview and pull_request
ci_runstarted, completedci_run
  • A merge sends pull_request with the action closed, and merged: true in the pull request.
  • edited on an issue or a pull request means that its title or its description changed.
  • A review sends nothing when its text is edited.
  • completed is sent for a run that ended or was cancelled. A run that was cancelled before it started sends completed with no started.

Fields of every body

  • event: the event name, the same as the X-Source-Event header.
  • action: the action, when the event has one.
  • repository: id, owner, name, full_name, url and private.
  • sender: the person who made the change, as id and login. It is null when no person made it, for example for a ping.
  • truncated: true when 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

  • status is running for started, and completed or cancelled for completed.
  • conclusion is success, failure, skipped, cancelled, or null while the run has none.
  • event is the trigger of the run: push, pull_request, schedule, manual, button or after.
  • trust is the trust level of the run: untrusted, trusted or protected.
{
  "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 2xx answer is a success. Any other status, no answer, or no answer within 10 seconds is a failure.
  • Source does not follow redirects. A 3xx answer 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 push for 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.