# Webhooks (/integrations/webhooks)

# Webhooks [#webhooks]

Your CI pipeline finishes a staging deploy, but it is not on Vercel and there
is no built-in trigger for it. A webhook trigger covers that case: the pipeline
sends one HTTP request, and the automation runs its checklists against the
build that just went out.

This page is a reference for the **Webhook** trigger. For building the rest of
an automation, read [Automate multi-step workflows](/tutorials/building-workflows).

## Before you start [#before-you-start]

- **Role.** Any workspace member who can create automations.
- **Plan.** Webhook runs count toward your plan like any other run. A request
  is refused if the workspace is out of runs or over its budget cap.

## Create a webhook trigger [#create-a-webhook-trigger]

1. Open **Automations** and click **Create automation**.
2. Under **Trigger**, choose **Webhook**. **Configure** has nothing to set: a
   webhook secret is generated when the automation is created.
3. Under **Details**, give it a **Name** and choose the **Project**, then
   click **Create automation** and add the steps it should run.
4. Open the automation's **Settings** tab. Under **Trigger configuration**,
   copy the **Webhook URL** and the **Webhook secret**.

Treat the secret like a password. Store it in your CI system's secret store,
not in a repository.

The secret is only shown here, in the dashboard. The [MCP server](/mcp), the
assistant and the Slack and Linear agents can read an automation's trigger
but never its secret, so nothing they are connected to can start a webhook
run. A webhook automation created over MCP by a connection without the
`mcp:run` scope starts turned off, and that connection cannot turn it on.

## Send the request [#send-the-request]

Send a `POST` to the **Webhook URL** with the secret in the `X-Webhook-Secret`
header. The request body is ignored, so you can send none.

```bash
curl -X POST "$STUNTDOUBLE_WEBHOOK_URL" \
  -H "X-Webhook-Secret: $STUNTDOUBLE_WEBHOOK_SECRET"
```

Here `STUNTDOUBLE_WEBHOOK_URL` and `STUNTDOUBLE_WEBHOOK_SECRET` are variables
you set in your own CI, holding the two values you copied.

The same request from a GitHub Actions step:

```yaml
- name: Run Stunt Double checks
  run: |
    curl --fail -X POST "${{ secrets.STUNTDOUBLE_WEBHOOK_URL }}" \
      -H "X-Webhook-Secret: ${{ secrets.STUNTDOUBLE_WEBHOOK_SECRET }}"
```

## Responses [#responses]

A successful request starts a run and returns its id:

```json
{ "run_id": "3f2b8c1e-..." }
```

The run then shows on the automation's runs list like any other.

| Status | Meaning                                                            |
| ------ | ------------------------------------------------------------------ |
| `200`  | The run started. The body carries `run_id`.                        |
| `400`  | The automation is turned off, or its trigger is not **Webhook**.   |
| `401`  | The `X-Webhook-Secret` header is missing or the secret is wrong.   |
| `402`  | The workspace has no runs left on its plan, or hit its budget cap. |
| `404`  | No automation exists at that URL.                                  |

Errors return a JSON body with an `error` message.

## Turn it off [#turn-it-off]

To stop accepting requests, turn the automation off. Requests then return
`400` until you turn it back on. Deleting the automation makes its URL return
`404`.

## Troubleshooting [#troubleshooting]

**`401` with the right secret.** Check the header name is exactly
`X-Webhook-Secret`, and that your CI is not adding quotes or a trailing
newline to the stored value.

**`400` straight after creating it.** The automation has to be on. Check its
**Active** switch, and that its trigger is still **Webhook**.

**The run starts but does nothing useful.** The webhook only starts the
automation. Check that it has steps, and that its checklists point at the
environment your pipeline just deployed.
