# Create a repository dispatch event

From **GitHub v3 REST API**.

`POST /repos/{owner}/{repo}/dispatches`

You can use this endpoint to trigger a webhook event called `repository_dispatch` when you want activity that happens outside of GitHub Enterprise Server to trigger a GitHub Actions workflow or GitHub App webhook. You must configure your GitHub Actions workflow or GitHub App to run when the `repository_dispatch` event occurs. For an example `repository_dispatch` webhook payload, see "[RepositoryDispatchEvent](https://docs.github.com/enterprise-server@3.0/webhooks/event-payloads/#repository_dispatch)."

The `client_payload` parameter is available for any extra information that your workflow might need. This parameter is a JSON payload that will be passed on when the webhook event is dispatched. For example, the `client_payload` can include a message that a user would like to send using a GitHub Actions workflow. Or the `client_payload` can be used as a test to debug your workflow.

This endpoint requires write access to the repository by providing either:

  - Personal access tokens with `repo` scope. For more information, see "[Creating a personal access token for the command line](https://docs.github.com/articles/creating-a-personal-access-token-for-the-command-line)" in the GitHub Help documentation.
  - GitHub Apps with both `metadata:read` and `contents:read&write` permissions.

This input example shows how you can use the `client_payload` as a test to debug your workflow.

## Parameters

### `owner`

- Location: path
- Required: true
- Type: `string`

### `repo`

- Location: path
- Required: true
- Type: `string`

## Request body

- Required: true
### `application/json`

- Type: `object`

```json
{
  "client_payload": {
    "integration": true,
    "unit": false
  },
  "event_type": "on-demand-test"
}
```

```json
{"properties":{"client_payload":{"additionalProperties":true,"description":"JSON payload with extra information about the webhook event that your action or worklow may use.","maxProperties":10,"type":"object"},"event_type":{"description":"A custom webhook event name.","maxLength":100,"minLength":1,"type":"string"}},"required":["event_type"],"type":"object"}
```

## Responses

### `204`

Response

### `422`

Validation failed

### `application/json`

- Type: `object`

Validation Error

```json
{"description":"Validation Error","properties":{"documentation_url":{"type":"string"},"errors":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"index":{"type":"integer"},"message":{"type":"string"},"resource":{"type":"string"},"value":{"oneOf":[{"nullable":true,"type":"string"},{"nullable":true,"type":"integer"},{"items":{"type":"string"},"nullable":true,"type":"array"}]}},"required":["code"],"type":"object"},"type":"array"},"message":{"type":"string"}},"required":["message","documentation_url"],"title":"Validation Error","type":"object"}
```

## Request examples

### cURL

```shell
curl --request POST \
  --url {protocol}://{hostname}/api/v3/repos/{owner}/{repo}/dispatches \
  --header 'content-type: application/json' \
  --data '{
  "client_payload": {
    "integration": true,
    "unit": false
  },
  "event_type": "on-demand-test"
}'
```