Docs

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.

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

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

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:

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

Responses

A successful request starts a run and returns its id:

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

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

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

Errors return a JSON body with an error message.

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

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.

On this page