GitHub Actions repository_dispatch Event Not Received

By Kaveh Alemi·Latchkey

A custom repository_dispatch event posted via the API does not start your workflow. The event_type does not match the filter, the API call lacked permission, or the workflow file is not on the default branch.

What this error means

You POST to the dispatches endpoint and get a 204, but no workflow run appears - or the API returns 403/404 and nothing is dispatched at all.

Terminal

# the API accepts this (204) but no run starts
curl -X POST -H "Authorization: token $TOKEN" \
  https://api.github.com/repos/org/repo/dispatches \
  -d '{"event_type":"deploy"}'
# workflow filters on: repository_dispatch: types: [release]  -> no match

Common causes

event_type does not match the types filter

If the workflow declares types: [release] but you dispatch event_type "deploy", the event is accepted by the API but matches no workflow.

Token lacks permission or repo is wrong

The dispatches API needs a token with contents:write (or repo scope for a PAT). A fine-grained token without it returns 403/404.

Workflow not on the default branch

repository_dispatch, like other repository-level events, only runs the workflow file from the default branch.

How to fix it

Align event_type with the types filter

Declare the event types you accept and dispatch a matching event_type. Read the payload via github.event.client_payload.

.github/workflows/dispatch.yml

on:
  repository_dispatch:
    types: [deploy]
jobs:
  go:
    runs-on: ubuntu-latest
    steps:
      - run: echo "ref ${{ github.event.client_payload.ref }}"

Use a token with the right scope

Give the dispatching token contents:write (fine-grained) or repo (classic PAT).
Confirm the workflow file is merged to the default branch.
A 204 only means the API accepted the event, not that a workflow matched - verify the types filter.

How to prevent it

Keep dispatch event_type values and the workflow types filter in sync.
Dispatch with a least-privilege token that still has contents:write.
Merge dispatch-triggered workflows to the default branch.

Frequently asked questions

What causes "repository_dispatch miss"?