Recipe
Trigger a GitHub Actions Workflow from Any Webhook
GitHub Actions can be started over HTTP, but only by a request in GitHub's exact format with a token in the header. Most services that send webhooks can do neither. An adapter in the middle is a few minutes of work.
17 November 2026 · 4 min read
The gap
The typical case is a static site. An editor publishes an article in the CMS, and the site should rebuild. The CMS can send a webhook when content changes. GitHub can start a workflow when it receives this:
POST https://api.github.com/repos/OWNER/REPO/dispatches
Authorization: Bearer <token>
Accept: application/vnd.github+json
{ "event_type": "content-published", "client_payload": { } }The CMS sends its own JSON, to a URL, usually with no way to add an Authorization header or change the body. So the two do not meet. The same gap appears with form tools, payment providers, monitoring services and anything else you would like to kick off a build, a deploy, a data sync or a test run.
Step 1: a workflow that listens
Add this to the repository's default branch. The types entry must match the event_type you will send.
name: Rebuild site
on:
repository_dispatch:
types: [content-published]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Show what triggered this
env:
ENTRY: ${{ github.event.client_payload.entry }}
run: echo "Rebuilding because of $ENTRY"
- run: npm ci && npm run buildNote how the payload value reaches the shell: through env, not pasted into the run line. Values from a webhook are untrusted input, and expanding them directly inside a script is a known injection risk.
Step 2: a token that can do only this
Create a fine-grained personal access token limited to the one repository, with the Contents permission set to read and write. That is what the dispatch endpoint requires. Give it an expiry date.
Step 3: capture the sender's webhook
Create a webhook.stream URL, register it in your CMS (or whichever service should trigger the build) and cause one event. Select the request in the inspector so you can see its real field names.
Step 4: the automation
Open Automations and choose Custom request.
| Setting | Value |
|---|---|
| Method | POST |
| URL | https://api.github.com/repos/OWNER/REPO/dispatches |
| Extra header | Authorization: Bearer github_pat_… |
| Extra header | Accept: application/vnd.github+json |
| Content type | application/json |
{
"event_type": "content-published",
"client_payload": {
"entry": "{{body.entry.slug | default: \"unknown\"}}",
"author": "{{body.entry.author.name}}",
"received_at": "{{request.timestamp}}"
}
}Replace the body.entry… paths with fields from your own sender. Everything under client_payload is available in the workflow as github.event.client_payload.
Add a condition if the sender fires for more than you want to build on:
| Field | Operator | Value |
|---|---|---|
body.event | equals | entry.published |
body.entry.status | does not equal | draft |
Step 5: test
Press Send test. GitHub answers 204 with an empty body when it accepts a dispatch, and the run appears under the repository's Actions tab a few seconds later. The common failures:
| GitHub answers | Usually means |
|---|---|
401 | The token is wrong, expired, or missing the Bearer prefix |
404 | The owner or repository name is wrong, or the token cannot see that repository |
403 | The token lacks the Contents write permission |
422 | The body is not what GitHub expects; check event_type is present |
204 but no run | The workflow file is not on the default branch, or types does not match |
Things worth knowing
- Keep the payload small. GitHub allows at most ten top-level properties in
client_payload. Send identifiers and let the workflow fetch what it needs. - Bursts cause bursts. Ten saves in the CMS are ten builds. Add a
concurrencygroup withcancel-in-progress: trueto the workflow so only the latest one finishes. - The token is stored with the automation. Anyone who has the dashboard link can read it, which is the reason for a single-repository, single-permission token. Do not share the link.
- Deliveries are not retried. If GitHub's API is unavailable at that moment, the dispatch is logged as failed and you re-run it by hand with Send test.
- Anyone who learns the webhook URL can trigger the workflow. It is long and unguessable, but treat it like a deploy hook: private, and attached to a workflow that is safe to run twice.
Variations
- One workflow with inputs: the
workflow_dispatchendpoint (/repos/OWNER/REPO/actions/workflows/FILE/dispatches) takes{"ref": "main", "inputs": {…}}and needs the Actions write permission instead. - Other CI systems: most have an HTTP trigger with a token header. The same pattern applies: capture, reshape, deliver.
- Tell the team as well: add a second automation that posts to chat when the same event arrives.
Capture the trigger first
Create a URL and point your CMS or other sender at it. Once you can see what it sends, the dispatch template takes a few minutes.
Keep reading
Transform a webhook payload
Reshape webhook JSON into the payload another API expects using a template: pick fields, keep types, set defaults and format values, with a live preview against a real request.
ReadGitHub webhooks to Discord
Send GitHub releases, failed workflow runs and new stars to a Discord channel with your own filters and message format, instead of Discord's all-or-nothing GitHub integration.
Read