Webhooks

A webhook sends an HTTPS POST with a JSON payload to a URL you choose whenever something happens in a repository: a push, a pull request opened, edited or merged, an issue comment, a workflow run started by hand or finished, a published release, a commit status or a deployment. Use webhooks to connect chat bots, deploy systems, external CI or any service that reacts to repository activity.

#How webhooks work

• Webhooks belong to one repository. You need the admin role on it to create, list or delete them.
• Each webhook has a payload URL (HTTPS only), a list of events, and a signing secret. The secret is stored encrypted with a key of its own and is never shown again after creation.
• When an event happens, Diffinery puts it on an internal queue. Within a few seconds the queue delivers it to every active webhook of the repository that subscribes to that event, in parallel.
• Each delivery is signed with an HMAC-SHA256 of the body using the webhook's secret, in the X-Hub-Signature-256 header, the same scheme GitHub uses.
• A delivery that fails with a network error, a timeout, 408, 429 or a 5xx status is retried up to five times over about four and a half hours, with the same X-GitHub-Delivery id. See Retries.
• Diffinery records the HTTP status and time of the most recent delivery attempt of each webhook.

#Events

A merged pull request is delivered as pull_request with "action": "closed" and "pull_request": { "merged": true }, like GitHub. edited is sent when the title or body actually changes, not for label or assignee changes. The release, status, deployment, deployment_status and repository_dispatch payloads have GitHub's shape (for example release holds the same release object as the REST API). The full payload of each event, with examples, is in Webhook events.

#Creating a webhook

#In the web UI

1. Open the repository, for example https://diffinery.com/acme/website.
2. Select Settings, then Webhooks in the sidebar (https://diffinery.com/acme/website/settings/webhooks).
3. Under Add a webhook, enter the Payload URL. It must start with https:// and name a public host: not localhost, a private or loopback address, or Diffinery itself.
4. Under Events, keep Everything checked to receive all events, or uncheck it and check the events you want: push, pull_request, pull_request_review, issues, issue_comment, workflow_run, workflow_dispatch. If Everything stays checked, the webhook receives every event regardless of the other boxes, including release, status, deployment, deployment_status, deployment_review and repository_dispatch. If you uncheck every box, the webhook also receives every event.
5. Optionally enter a Secret. Leave it empty to have Diffinery generate one.
6. Select Add webhook.

The page then shows Webhook created for your URL with the signing secret. Copy it now: it is not shown again. If you lose it, delete the webhook and create a new one.

Note: The web form only offers the events listed above as separate checkboxes. To subscribe to release, status, deployment, deployment_status, deployment_review or repository_dispatch without receiving everything, create the webhook with the API and list the events you want.

#With the API

POST /api/v3/repos/{owner}/{repo}/hooks creates a webhook. It needs a token with the admin scope for an account with the admin role on the repository.

curl -sS -X POST \
  -H "Authorization: Bearer dfy_..." \
  -H "Content-Type: application/json" \
  https://diffinery.com/api/v3/repos/acme/website/hooks \
  -d '{
    "config": { "url": "https://example.com/hooks/diffinery", "secret": "my-long-random-secret" },
    "events": ["push", "release", "status"]
  }'

A request without config.url fails with 422 and config.url is required.

The response (201) is the webhook, in GitHub's hook format. When you didn't send a secret, it also contains the generated secret, once:

{
  "type": "Repository",
  "id": "0b9a6f3e2c1d4f5a8e7b6c5d4e3f2a1b",
  "name": "web",
  "active": true,
  "events": ["push", "release", "status"],
  "config": { "url": "https://example.com/hooks/diffinery", "content_type": "json", "insecure_ssl": "0" },
  "updated_at": "2026-10-13T09:00:00Z",
  "created_at": "2026-10-13T09:00:00Z",
  "url": "https://diffinery.com/api/v3/repos/acme/website/hooks/0b9a6f3e2c1d4f5a8e7b6c5d4e3f2a1b",
  "ping_url": "https://diffinery.com/api/v3/repos/acme/website/hooks/0b9a6f3e2c1d4f5a8e7b6c5d4e3f2a1b/pings",
  "deliveries_url": "https://diffinery.com/api/v3/repos/acme/website/hooks/0b9a6f3e2c1d4f5a8e7b6c5d4e3f2a1b/deliveries",
  "last_response": { "code": null, "status": "unused", "message": null }
}

When you send config.secret, the response has no secret field: store your own copy. Webhook ids are 32-character hexadecimal strings. Other GitHub fields such as name, active and config.content_type are ignored on create. Payloads are always JSON. Event names are not validated: a name that is not in the table above never matches anything.

The same request with the CLI (install it with curl -fsSL https://diffinery.com/install | bash, then diffinery login):

cat > hook.json <<'EOF'
{ "config": { "url": "https://example.com/hooks/diffinery" }, "events": ["push"] }
EOF
diffinery api POST /repos/acme/website/hooks --input hook.json

#Listing and deleting webhooks

# List (the secret is never included)
curl -sS -H "Authorization: Bearer dfy_..." https://diffinery.com/api/v3/repos/acme/website/hooks

# Delete
curl -sS -X DELETE -H "Authorization: Bearer dfy_..." \
  https://diffinery.com/api/v3/repos/acme/website/hooks/0b9a6f3e2c1d4f5a8e7b6c5d4e3f2a1b

The list (paginated with per_page and page) returns the same objects, never with the secret:

[
  {
    "type": "Repository",
    "id": "0b9a6f3e2c1d4f5a8e7b6c5d4e3f2a1b",
    "name": "web",
    "active": true,
    "events": ["push", "release", "status"],
    "config": { "url": "https://example.com/hooks/diffinery", "content_type": "json", "insecure_ssl": "0" },
    "updated_at": "2026-10-13T09:30:02Z",
    "created_at": "2026-10-13T09:00:00Z",
    "url": "https://diffinery.com/api/v3/repos/acme/website/hooks/0b9a6f3e2c1d4f5a8e7b6c5d4e3f2a1b",
    "ping_url": "https://diffinery.com/api/v3/repos/acme/website/hooks/0b9a6f3e2c1d4f5a8e7b6c5d4e3f2a1b/pings",
    "deliveries_url": "https://diffinery.com/api/v3/repos/acme/website/hooks/0b9a6f3e2c1d4f5a8e7b6c5d4e3f2a1b/deliveries",
    "last_response": { "code": 200, "status": "active", "message": null }
  }
]

ping_url and deliveries_url are included for GitHub clients, but Diffinery has no ping or delivery-history endpoints, so requests to them return 404.

DELETE returns 204. There is no endpoint to edit a webhook: to change its URL, events or secret, delete it and create a new one. In the web UI, select Delete next to the webhook.

#Delivery

#Request

POST /hooks/diffinery HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: Diffinery-Hookshot/1
X-GitHub-Event: pull_request
X-GitHub-Delivery: 7d3f0c2a9b8e4d1fa6c5b4e3d2c1b0a9
X-Diffinery-Event: pull_request
X-Hub-Signature-256: sha256=4b1c0e2f...

{"action":"opened","number":42,"headRef":"fix-typo", ...}

The body is compact JSON (no extra whitespace). Every payload has repository and sender objects. repository is GitHub's full repository object, the same one GET /api/v3/repos/{owner}/{repo} returns: its id is a number, and private and visibility give the repository's real visibility (false and public for a public repository). See Webhook events.

#Timeouts, redirects and retries

Respond quickly with a 2xx and do slow work afterwards, so that deliveries don't time out.

#Retries

When an attempt fails in a way that may be temporary, Diffinery tries the same delivery again later:

The retries come 1 minute after the first failed attempt, then 5 minutes, 30 minutes, 1 hour and 3 hours after each further failure: at most six attempts, the last about 4 hours 36 minutes after the first. The delays are minimums; queue processing can add a few seconds.

• Every attempt of one delivery has the same X-GitHub-Delivery id, the same X-GitHub-Event and the same body, so you can use the id to drop repeats.
• Each attempt is signed and sent with the webhook's URL and secret as they are at that moment. If the webhook was deleted in the meantime, the remaining retries are dropped.
• The delivery fails for good when an attempt gets a status that isn't retried, or when the sixth attempt also fails. Diffinery then stops without further notice: there is no email, no automatic disabling of the webhook, and no manual redelivery. The webhook's last status shows the result of the final attempt.
• Every attempt updates the webhook's last delivery status and time, so a delivery that succeeds on a retry shows as successful.
• Deliveries for other events are not held back while one is being retried, so a retried delivery can arrive after newer ones.

#Delivery status

Diffinery keeps the status and time of the most recent delivery attempt of each webhook (retries included), not a full history:

• On the Webhooks settings page, each webhook shows a status icon (green for 2xx, red otherwise), its events, whether it is active, and last delivery <status> <time>, or no deliveries yet.
• GET /api/v3/repos/{owner}/{repo}/hooks returns last_response.code and last_response.status, with the delivery time in updated_at.

A status of 0 means the request did not get an HTTP response: a timeout after 10 seconds, a DNS failure or a refused connection. Failed deliveries are retried automatically, but there is no redelivery button and no ping event: to test a webhook, trigger a real event, for example by pushing a branch or opening an issue.

#Verifying signatures

Always verify X-Hub-Signature-256 before trusting a payload. Compute the HMAC-SHA256 of the raw request body bytes with your secret as the key (UTF-8), hex-encode it, prefix sha256=, and compare it with the header using a constant-time comparison. Do not parse and re-serialize the JSON before computing the HMAC.

#Node.js

import crypto from "node:crypto";
import http from "node:http";

const secret = process.env.WEBHOOK_SECRET;

function verify(rawBody, header) {
  if (typeof header !== "string" || !header.startsWith("sha256=")) return false;
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(header);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

http
  .createServer((req, res) => {
    const chunks = [];
    req.on("data", (chunk) => chunks.push(chunk));
    req.on("end", () => {
      const body = Buffer.concat(chunks);
      if (!verify(body, req.headers["x-hub-signature-256"])) {
        res.writeHead(401).end("bad signature");
        return;
      }
      const event = req.headers["x-github-event"];
      const payload = JSON.parse(body.toString("utf8"));
      console.log(event, payload.action ?? "", payload.repository.full_name, payload.sender.login);
      res.writeHead(204).end();
    });
  })
  .listen(3000);

#Python

Standard library only:

import hashlib
import hmac
import json
import os
from http.server import BaseHTTPRequestHandler, HTTPServer

SECRET = os.environ["WEBHOOK_SECRET"].encode("utf-8")

def verify(body: bytes, header: str | None) -> bool:
    if not header or not header.startswith("sha256="):
        return False
    expected = "sha256=" + hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

class Hook(BaseHTTPRequestHandler):
    def do_POST(self):
        body = self.rfile.read(int(self.headers.get("Content-Length", "0")))
        if not verify(body, self.headers.get("X-Hub-Signature-256")):
            self.send_response(401)
            self.end_headers()
            return
        payload = json.loads(body)
        print(self.headers.get("X-GitHub-Event"), payload.get("action"), payload["repository"]["full_name"])
        self.send_response(204)
        self.end_headers()

HTTPServer(("", 3000), Hook).serve_forever()

#Check a signature by hand

printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | sed 's/^.*= /sha256=/'

#GitHub compatibility

Diffinery webhooks use GitHub's delivery format, so many GitHub webhook receivers and signature-verification libraries work unchanged:

• The same headers: X-GitHub-Event, X-GitHub-Delivery and X-Hub-Signature-256, plus X-Diffinery-Event.
• The same signature scheme (HMAC-SHA256, sha256= prefix, hex).
• The same event names and the same action values for the actions Diffinery sends.
• Payloads have GitHub's full repository object (numeric id, node_id, owner, private, visibility, default_branch, URLs and so on), a sender, GitHub-style pull_request and issue objects, and pull_request.merged on closed.
• release, status, deployment, deployment_status, deployment_review and repository_dispatch payloads have GitHub's structure, with the release, status and deployment fields GitHub receivers read. workflow_dispatch has GitHub's inputs, ref and workflow fields.
• The hooks API returns GitHub's hook object (type, name, config, last_response, ...).

Differences to plan for:

Diffinery-specific fields in the small payloads use camelCase, for example headRef, headSha, baseRef, commentId, runId and at.

#Security

• Payload URLs must use HTTPS.
• The secret is stored with the webhook and is shown only once in the web UI (and returned once by the create API). Use a long random value, and keep it in your receiver's secret store.
• Verify the signature on every request, and reject requests without one.
• Creating a webhook is recorded in the audit log as repo.webhook.create, and deleting one as repo.webhook.delete, both from the web UI and from the API (API changes carry "via": "api" in the detail).
• On an archived repository, webhooks can't be created or deleted: the request fails with 403 and repository is archived (read-only).
• Payloads from a private repository say so ("private": true, "visibility": "private"), so a receiver can decide what it may show or forward.
• Payloads never contain Actions secrets, tokens or file contents.

#Troubleshooting