Provider guide
GitHub webhooks with Hooksmith
To verify a GitHub webhook signature, compute HMAC-SHA256 of the raw request body with your webhook secret and compare it, in constant time, with the X-Hub-Signature-256 header (sha256=<hex>). Hooksmith does that check for every request, then filters the event and forwards a reshaped body to your endpoint.
How GitHub signs webhooks
Hooksmith checks X-Hub-Signature-256 against the raw request bytes.
- Header
- X-Hub-Signature-256, in the form sha256=<hex>.
- Algorithm
- HMAC-SHA256, hex encoded, compared in constant time.
- What is signed
- The raw request body.
- Key
- The secret you typed into the GitHub webhook form.
- Replay window
- None. The signature has no timestamp, so there is no tolerance setting.
- GitHub also sends the older SHA-1 X-Hub-Signature header when a secret is set. Hooksmith ignores it and checks only the SHA-256 header.
- A failed check answers 401 VERIFICATION_FAILED and stores nothing.
- A second request with the same X-GitHub-Delivery value within 24 hours is reported as a duplicate and is not delivered again.
Set it up
Hooksmith turns the provider preset into a hook you own. The signing secret exists before the endpoint does, so store it first, then deploy, then enter the URL in the provider dashboard. Secrets live in your workspace vault and never go in the YAML. Store GITHUB_WEBHOOK_SECRET, DESTINATION_URL.
- In the repository (or organization), open Settings, then Webhooks, and choose Add webhook.
- Set the payload URL to the /h/<id> URL that hooksmith deploy printed, and the content type to application/json.
- Enter a random string as the secret. It must be the same value you stored as GITHUB_WEBHOOK_SECRET.
- Choose the events to send. For the example below, select only the push event. The hook also checks X-GitHub-Event, as a second layer if the webhook is later set to send more events.
hooksmith login hooksmith new github-main-pushes --preset github --yes # paste the example hook into .hooksmith/hooks/github-main-pushes.yaml hooksmith secrets set GITHUB_WEBHOOK_SECRET hooksmith secrets set DESTINATION_URL hooksmith test github-main-pushes --payload ./push.json --header "X-GitHub-Event: push" hooksmith deploy github-main-pushes # prints the /h/<id> URL
hooksmith new writes the preset's starter hook. Replace its contents with the example below, or edit it by hand. The CLI's built-in test sample is generic, so pass your own payload with --payload; a matching one is in the next section. This example reads request headers, so the test command also passes them with --header (CLI 0.6.4 or later). The command reference is in the docs.
Forward pushes to main as a chat message
This hook skips everything except pushes to refs/heads/main and sends a body with the event name, a text line and a compare link. The event name comes from the X-GitHub-Event header, which a condition reads as @headers.x-github-event. The branch comes from the ref field in the body.
apiVersion: hooksmith/v1
kind: Hook
metadata:
name: github-main-pushes
description: Pushes to main as a chat message
spec:
source:
preset: github
destinations:
- name: chat
url: ${DESTINATION_URL}
method: POST
timeout: 8s
retries:
max: 3
backoff: exponential
initialDelay: 500ms
transform:
engine: handlebars
fields:
event: "{{{@headers.x-github-event}}}"
text: "{{{pusher.name}}} pushed to {{{repository.full_name}}}: {{{firstLine head_commit.message}}}"
url: "{{{compare}}}"
conditions:
- if: '@headers.x-github-event != "push" || ref != "refs/heads/main"'
then:
skip: true
variables:
- name: GITHUB_WEBHOOK_SECRET
from: secret
- name: DESTINATION_URL
from: secret
{
"ref": "refs/heads/main",
"compare": "https://github.com/acme/app/compare/1111111...2222222",
"repository": { "full_name": "acme/app" },
"pusher": { "name": "octocat" },
"head_commit": { "message": "Fix retry backoff\n\nLonger body." }
}- DESTINATION_URL is a workspace secret, so the URL stays out of the YAML. Store it with hooksmith secrets set DESTINATION_URL.
- Values use triple braces so quotes, ampersands, apostrophes and equals signs reach your endpoint as typed. With double braces, template output is HTML-escaped.
- Header names are lowercase in conditions and templates: @headers.x-github-event works, @headers.X-GitHub-Event fails validation with a message that gives the lowercase spelling. The header is also available in templates as {{@headers.x-github-event}}.
- Pings, other event types, tags and pushes to other branches are skipped. A skipped event is still stored and visible in the dashboard with its reason.
- A local hooksmith test sends no request headers unless you pass them, so without --header "X-GitHub-Event: push" this hook reports the sample as skipped. In the dashboard, the Send test event panel has a Headers box for the same purpose. The --header flag needs CLI 0.6.4 or later.
GitHub events worth subscribing to
GitHub puts the event name in the X-GitHub-Event header, which a Hooksmith condition or template reads as @headers.x-github-event. The values below are the names GitHub sends. You can also choose the events on the GitHub webhook itself, so that only those are sent.
- push
- Commits pushed to a branch or tag. The ref field tells which.
- pull_request
- Opened, closed, synchronized and so on. See the action field.
- issues
- Issue opened, edited, closed. See the action field.
- issue_comment
- A comment on an issue or pull request.
- release
- A release was published or changed.
- workflow_run
- A GitHub Actions workflow run requested or completed.
- check_run
- A check run was created or completed.
- ping
- Sent once when you create the webhook.
Test against localhost
The Hooksmith desktop app for Mac can tunnel stored events to a server on your machine. In raw mode it replays the original body bytes and the stored provider headers. Proxy headers such as x-forwarded-host are never stored, so they are not replayed. The target must be localhost, 127.0.0.1, [::1] or a *.localhost name. Get it on the download page.
GitHub signatures carry no timestamp, so an older event can be resent.
Questions
How do I verify a GitHub webhook signature?
Compute HMAC-SHA256 of the raw request body using the webhook secret as the key, hex encode it, prefix it with sha256=, and compare it to the X-Hub-Signature-256 header with a constant-time function. Use the raw bytes, not re-serialized JSON. Hooksmith does this automatically for a hook with source.preset: github.
Does GitHub retry failed webhook deliveries?
No. GitHub does not automatically redeliver failed deliveries, and it treats a response slower than 10 seconds as a failure. You can redeliver manually from the webhook's Recent Deliveries, for deliveries from the past 3 days. Hooksmith answers 200 once the event is stored, so your own endpoint being down does not fail the GitHub delivery. Hooksmith retries your endpoint on 5xx responses, 408, 425, 429 and network errors. GitHub's docs do not say whether a redelivery keeps its X-GitHub-Delivery value. If a redelivery of an event Hooksmith already accepted shows up as a duplicate, use hooksmith replay <event-id>, which skips the duplicate check.
Why do I get a signature error from GitHub webhooks?
Check that GITHUB_WEBHOOK_SECRET holds exactly the secret entered in GitHub, and that the webhook is set to application/json. Hooksmith only reads X-Hub-Signature-256, so a webhook with no secret set sends no such header and is rejected with a 401.
Can I filter GitHub events by type in Hooksmith?
Yes. A condition can read the X-GitHub-Event header as @headers.x-github-event, for example @headers.x-github-event != "push" to skip everything except pushes. Header names are lowercase there. You can combine it with body fields such as ref, action or sender.type. You can also choose the events on the GitHub webhook itself, so that only those are sent. The generated preset hook, for example, skips events where sender.type is Bot.
Can I replay a GitHub event?
Yes. hooksmith replay <event-id> or the dashboard re-runs the stored request through the hook's current YAML. Replays skip signature checks and duplicate detection and are not counted against your event quota. The hook must keep payloads, which is the default.
Other providers
All providers are listed on webhook providers. Hooks are metered by events processed: see pricing.