Triggering a RepositoryDispatch webhook

Note: GitHub Actions are currently available as a limited public beta, which means you should avoid using it for high-value workflows and content during this beta period. Creating workflows that use GitHub Actions is limited to private repositories during the limited public beta.

Features and requirements may change at any time during this period. You can request to join the limited public beta on the GitHub Actions page. If you're participating in the beta, please contact support if you have any questions.

Repository dispatch provides new messaging that leverages GitHub's webhook delivery mechanism to automate your workflows based on events of your own domain.

How to trigger the RepositoryDispatch webhook

You can use the dispatches endpoint to trigger a RepositoryDispatch event to all listeners. Only GitHub Apps can trigger this webhook event.

POST /repos/:owner/:repo/dispatches

or for organizations:

POST /repos/:org/:repo/dispatches
  1. Generate a Personal Access Token with repo scope, which gives you write access.
  2. Send a POST to the dispatches endpoint with a JSON body like this:
    { "event_type" : "YOUR_CUSTOM_EVENT_NAME"}

  3. On success, you will receive a RepositoryDispatch webhook with the value of the event_type property being the action in the webhook body.

Input

{
  "event_type": "html.preview"
}

Example cURL input

curl -XPOST -u "Codertocat:<token>" \
-H "Accept: application/vnd.github.everest-preview+json"  \
-H "Content-Type: application/json" \
https://api.github.com/repos/octo-org/octo-repo/dispatches
--data '{"event_type": "html.preview"}'

Webhook payload example

Status: 204 No Content
{
  "action": "html.preview",
  "branch": "master",
  "ref": "270d8ccac611aa63ce26a31049570fb0e4f41586",
  "repository": {
    "id": 17273051,
    "node_id": "MDEwOlJlcG9zaXRvcnkxNzI3MzA1MQ==",
    "name": "octo-repo",
    "full_name": "octo-org/octo-repo",
    "private": true,
    "owner": {
      "login": "octo-org",
      "id": 6811672,
      "node_id": "MDEyOk9yZ2FuaXphdGlvbjY4MTE2NzI=",
      "avatar_url": "https://avatars3.githubusercontent.com/u/6811672?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/octo-org",
      "html_url": "https://github.com/octo-org",
      "followers_url": "https://api.github.com/users/octo-org/followers",
      "following_url": "https://api.github.com/users/octo-org/following{/other_user}",
      "gists_url": "https://api.github.com/users/octo-org/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/octo-org/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/octo-org/subscriptions",
      "organizations_url": "https://api.github.com/users/octo-org/orgs",
      "repos_url": "https://api.github.com/users/octo-org/repos",
      "events_url": "https://api.github.com/users/octo-org/events{/privacy}",
      "received_events_url": "https://api.github.com/users/octo-org/received_events",
      "type": "Organization",
      "site_admin": false
    },
    "html_url": "https://github.com/octo-org/octo-repo",
    "description": "My first repo on GitHub!",
    "fork": false,
    "url": "https://api.github.com/repos/octo-org/octo-repo",
    "forks_url": "https://api.github.com/repos/octo-org/octo-repo/forks",
    "keys_url": "https://api.github.com/repos/octo-org/octo-repo/keys{/key_id}",
    "collaborators_url": "https://api.github.com/repos/octo-org/octo-repo/collaborators{/collaborator}",
    "teams_url": "https://api.github.com/repos/octo-org/octo-repo/teams",
    "hooks_url": "https://api.github.com/repos/octo-org/octo-repo/hooks",
    "issue_events_url": "https://api.github.com/repos/octo-org/octo-repo/issues/events{/number}",
    "events_url": "https://api.github.com/repos/octo-org/octo-repo/events",
    "assignees_url": "https://api.github.com/repos/octo-org/octo-repo/assignees{/user}",
    "branches_url": "https://api.github.com/repos/octo-org/octo-repo/branches{/branch}",
    "tags_url": "https://api.github.com/repos/octo-org/octo-repo/tags",
    "blobs_url": "https://api.github.com/repos/octo-org/octo-repo/git/blobs{/sha}",
    "git_tags_url": "https://api.github.com/repos/octo-org/octo-repo/git/tags{/sha}",
    "git_refs_url": "https://api.github.com/repos/octo-org/octo-repo/git/refs{/sha}",
    "trees_url": "https://api.github.com/repos/octo-org/octo-repo/git/trees{/sha}",
    "statuses_url": "https://api.github.com/repos/octo-org/octo-repo/statuses/{sha}",
    "languages_url": "https://api.github.com/repos/octo-org/octo-repo/languages",
    "stargazers_url": "https://api.github.com/repos/octo-org/octo-repo/stargazers",
    "contributors_url": "https://api.github.com/repos/octo-org/octo-repo/contributors",
    "subscribers_url": "https://api.github.com/repos/octo-org/octo-repo/subscribers",
    "subscription_url": "https://api.github.com/repos/octo-org/octo-repo/subscription",
    "commits_url": "https://api.github.com/repos/octo-org/octo-repo/commits{/sha}",
    "git_commits_url": "https://api.github.com/repos/octo-org/octo-repo/git/commits{/sha}",
    "comments_url": "https://api.github.com/repos/octo-org/octo-repo/comments{/number}",
    "issue_comment_url": "https://api.github.com/repos/octo-org/octo-repo/issues/comments{/number}",
    "contents_url": "https://api.github.com/repos/octo-org/octo-repo/contents/{+path}",
    "compare_url": "https://api.github.com/repos/octo-org/octo-repo/compare/{base}...{head}",
    "merges_url": "https://api.github.com/repos/octo-org/octo-repo/merges",
    "archive_url": "https://api.github.com/repos/octo-org/octo-repo/{archive_format}{/ref}",
    "downloads_url": "https://api.github.com/repos/octo-org/octo-repo/downloads",
    "issues_url": "https://api.github.com/repos/octo-org/octo-repo/issues{/number}",
    "pulls_url": "https://api.github.com/repos/octo-org/octo-repo/pulls{/number}",
    "milestones_url": "https://api.github.com/repos/octo-org/octo-repo/milestones{/number}",
    "notifications_url": "https://api.github.com/repos/octo-org/octo-repo/notifications{?since,all,participating}",
    "labels_url": "https://api.github.com/repos/octo-org/octo-repo/labels{/name}",
    "releases_url": "https://api.github.com/repos/octo-org/octo-repo/releases{/id}",
    "deployments_url": "https://api.github.com/repos/octo-org/octo-repo/deployments",
    "created_at": "2014-02-28T02:42:51Z",
    "updated_at": "2018-10-10T15:58:51Z",
    "pushed_at": "2018-10-10T15:58:47Z",
    "git_url": "git://github.com/octo-org/octo-repo.git",
    "ssh_url": "git@github.com:octo-org/octo-repo.git",
    "clone_url": "https://github.com/octo-org/octo-repo.git",
    "svn_url": "https://github.com/octo-org/octo-repo",
    "homepage": "",
    "size": 59,
    "stargazers_count": 0,
    "watchers_count": 0,
    "language": "JavaScript",
    "has_issues": true,
    "has_projects": true,
    "has_downloads": true,
    "has_wiki": true,
    "has_pages": false,
    "forks_count": 1,
    "mirror_url": null,
    "archived": false,
    "open_issues_count": 23,
    "license": null,
    "forks": 1,
    "open_issues": 23,
    "watchers": 0,
    "default_branch": "master"
  },
  "organization": {
    "login": "octo-org",
    "id": 6811672,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjY4MTE2NzI=",
    "url": "https://api.github.com/orgs/octo-org",
    "repos_url": "https://api.github.com/orgs/octo-org/repos",
    "events_url": "https://api.github.com/orgs/octo-org/events",
    "hooks_url": "https://api.github.com/orgs/octo-org/hooks",
    "issues_url": "https://api.github.com/orgs/octo-org/issues",
    "members_url": "https://api.github.com/orgs/octo-org/members{/member}",
    "public_members_url": "https://api.github.com/orgs/octo-org/public_members{/member}",
    "avatar_url": "https://avatars3.githubusercontent.com/u/6811672?v=4",
    "description": "Working better together!"
  },
  "sender": {
    "login": "Codertocat",
    "id": 21031067,
    "node_id": "MDQ6VXNlcjIxMDMxMDY3",
    "avatar_url": "https://avatars1.githubusercontent.com/u/21031067?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/Codertocat",
    "html_url": "https://github.com/Codertocat",
    "followers_url": "https://api.github.com/users/Codertocat/followers",
    "following_url": "https://api.github.com/users/Codertocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/Codertocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/Codertocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/Codertocat/subscriptions",
    "organizations_url": "https://api.github.com/users/Codertocat/orgs",
    "repos_url": "https://api.github.com/users/Codertocat/repos",
    "events_url": "https://api.github.com/users/Codertocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/Codertocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "installation": {
    "id": 375706,
    "node_id": "MDIzOkludGVncmF0aW9uSW5zdGFsbGF0aW9uMzc1NzA2"
  }
}