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:

What GitHub needs
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.

.github/workflows/rebuild.yml
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 build

Note 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.

SettingValue
MethodPOST
URLhttps://api.github.com/repos/OWNER/REPO/dispatches
Extra headerAuthorization: Bearer github_pat_…
Extra headerAccept: application/vnd.github+json
Content typeapplication/json
Dispatch template
{
  "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:

FieldOperatorValue
body.eventequalsentry.published
body.entry.statusdoes not equaldraft

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 answersUsually means
401The token is wrong, expired, or missing the Bearer prefix
404The owner or repository name is wrong, or the token cannot see that repository
403The token lacks the Contents write permission
422The body is not what GitHub expects; check event_type is present
204 but no runThe 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 concurrency group with cancel-in-progress: true to 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.
Keeping it runningA free URL lives for up to 7 days, which is enough to build this and prove it works. To leave it in place, a Pro pass keeps the same URL alive for 30 days ($3) or 1 year ($19). It is a single payment, not a subscription, and nothing has to be reconfigured at the sender.

Variations

  • One workflow with inputs: the workflow_dispatch endpoint (/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.