# Trigger automation webhook (/api/automations/webhook)

<!-- agent-signals: reading_time_min: 4 · est_tokens: 1956 · updated: 2026-09-23 -->
Related: [Trigger automation](/api/automations/trigger.md), [Create assistant message](/api/assistant/create-assistant-message-v2.md)

Use this endpoint to run a custom automation with a **Webhook** trigger. Each request queues a run that uses the automation's saved prompt and reads the full repository history. This endpoint ignores request bodies.

This endpoint only supports [custom automations](/automations/create) with a webhook trigger. Predefined automations and automations with any other trigger return a `404` response. To trigger a scheduled custom automation on demand instead, use [Trigger automation](/api/automations/trigger).

## Use cases [#use-cases]

* **CI/CD pipelines**: Run a custom automation on every merge to `main` or after a release, without waiting for a scheduled run.
* **Release events**: Run a custom automation from a release script when you cut a tag or publish a new SDK version.
* **Internal tooling**: Trigger automations from internal dashboards, Slack commands, or scheduled jobs you already run.

## Get the webhook URL and auth header [#get-the-webhook-url-and-auth-header]

Open the [Automations](https://app.mintlify.com/products/automations) page in your dashboard and click the <Icon icon="<svg xmlns=&#x22;http://www.w3.org/2000/svg&#x22; viewBox=&#x22;0 0 24 24&#x22; fill=&#x22;none&#x22;><path d=&#x22;M15.5 12C15.5 13.933 13.933 15.5 12 15.5C10.067 15.5 8.5 13.933 8.5 12C8.5 10.067 10.067 8.5 12 8.5C13.933 8.5 15.5 10.067 15.5 12Z&#x22; stroke=&#x22;currentColor&#x22; stroke-width=&#x22;1.5&#x22;/><path d=&#x22;M21.011 14.0965C21.5329 13.9558 21.7939 13.8854 21.8969 13.7508C22 13.6163 22 13.3998 22 12.9669V11.0332C22 10.6003 22 10.3838 21.8969 10.2493C21.7938 10.1147 21.5329 10.0443 21.011 9.90358C19.0606 9.37759 17.8399 7.33851 18.3433 5.40087C18.4817 4.86799 18.5509 4.60156 18.4848 4.44529C18.4187 4.28902 18.2291 4.18134 17.8497 3.96596L16.125 2.98673C15.7528 2.77539 15.5667 2.66972 15.3997 2.69222C15.2326 2.71472 15.0442 2.90273 14.6672 3.27873C13.208 4.73448 10.7936 4.73442 9.33434 3.27864C8.95743 2.90263 8.76898 2.71463 8.60193 2.69212C8.43489 2.66962 8.24877 2.77529 7.87653 2.98663L6.15184 3.96587C5.77253 4.18123 5.58287 4.28891 5.51678 4.44515C5.45068 4.6014 5.51987 4.86787 5.65825 5.4008C6.16137 7.3385 4.93972 9.37763 2.98902 9.9036C2.46712 10.0443 2.20617 10.1147 2.10308 10.2492C2 10.3838 2 10.6003 2 11.0332V12.9669C2 13.3998 2 13.6163 2.10308 13.7508C2.20615 13.8854 2.46711 13.9558 2.98902 14.0965C4.9394 14.6225 6.16008 16.6616 5.65672 18.5992C5.51829 19.1321 5.44907 19.3985 5.51516 19.5548C5.58126 19.7111 5.77092 19.8188 6.15025 20.0341L7.87495 21.0134C8.24721 21.2247 8.43334 21.3304 8.6004 21.3079C8.76746 21.2854 8.95588 21.0973 9.33271 20.7213C10.7927 19.2644 13.2088 19.2643 14.6689 20.7212C15.0457 21.0973 15.2341 21.2853 15.4012 21.3078C15.5682 21.3303 15.7544 21.2246 16.1266 21.0133L17.8513 20.034C18.2307 19.8187 18.4204 19.711 18.4864 19.5547C18.5525 19.3984 18.4833 19.132 18.3448 18.5991C17.8412 16.6616 19.0609 14.6226 21.011 14.0965Z&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/></svg>" /> settings button on a custom automation with a webhook trigger. The trigger card shows the full webhook URL and a **Copy auth header** action for the `Authorization: Bearer <api-key>` header template.

Replace `<api-key>` with an unexpired organization API key with write access. Create or manage keys on the [API keys](https://app.mintlify.com/settings/organization/api-keys) page. Automations do not create, store, or rotate keys on your behalf.

## Example [#example]

Trigger a webhook automation from a GitHub Action whenever code merges to `main`:

```yaml title=".github/workflows/trigger-docs.yml"
on:
  push:
    branches: [main]

jobs:
  trigger:
    runs-on: ubuntu-latest
    steps:
      - run: |
          curl -fsS -X POST \
            "https://api.mintlify.com/v2/workflow/$PROJECT_ID/$WORKFLOW_ID/webhook" \
            -H "Authorization: Bearer ${{ secrets.MINTLIFY_API_KEY }}"
        env:
          PROJECT_ID: ${{ vars.MINTLIFY_PROJECT_ID }}
          WORKFLOW_ID: ${{ vars.MINTLIFY_WORKFLOW_ID }}
```

## Rate limits [#rate-limits]

This endpoint shares a rate limit with [Trigger update](/api/update/trigger) and [Trigger automation](/api/automations/trigger): up to 10 requests per 10 seconds per organization. Each queued run consumes credits at the same rate as any other custom automation run. See [Credit pricing](/credits).

`POST /v2/workflow/{projectId}/{workflowSchemaId}/webhook`

Queue a run of a custom automation that has a webhook trigger, instead of waiting for the trigger's configured event. Useful for running automations from CI/CD pipelines, release scripts, or any other system that already emits events. Only custom automations with a webhook trigger can be triggered; other triggers return a `404` response.

Authenticate with an organization API key that has write access.

## OpenAPI

```json
{
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "projectId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Your project ID. Copy it from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard."
    },
    {
      "name": "workflowSchemaId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "The ID of the automation to trigger. Copy it from the automation's settings panel on the [Automations](https://app.mintlify.com/products/automations) page in your dashboard."
    }
  ],
  "responses": {
    "202": {
      "description": "Automation run queued successfully.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "runId": {
                "type": "string",
                "description": "The ID of the queued automation run. Appears in the run history on the [Automations](https://app.mintlify.com/products/automations) page."
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "The automation ID is malformed.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message."
              }
            }
          }
        }
      }
    },
    "402": {
      "description": "AI credits are exhausted for this billing cycle. Upgrade your plan or wait for your credits to renew.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message."
              }
            }
          }
        }
      }
    },
    "404": {
      "description": "The automation was not found, is not active, does not belong to this project, or is not configured with a webhook trigger.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message."
              }
            }
          }
        }
      }
    },
    "503": {
      "description": "Credit check failed. Retry the request.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "Error message."
              }
            }
          }
        }
      }
    }
  }
}
```