Trigger automation 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.

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

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

Open the Automations page in your dashboard and click the 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 page. Automations do not create, store, or rotate keys on your behalf.

Example

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

.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

This endpoint shares a rate limit with Trigger update and Trigger automation: 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.

OpenAPI

admin-openapi.json

openapi: 3.0.1
info:
  title: Mintlify Admin API
  description: >-
    An API for administrative operations including documentation updates and
    agent management.
  version: 2.0.0
servers:
  - url: https://api.mintlify.com
security:
  - bearerAuth: []
paths:
  /v2/workflow/{projectId}/{workflowSchemaId}/webhook:
    post:
      summary: Trigger automation webhook
      description: >-
        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.
      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:
                $ref: '#/components/schemas/Error'
        '402':
          description: >-
            AI credits are exhausted for this billing cycle. Upgrade your plan
            or wait for your credits to renew.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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:
                $ref: '#/components/schemas/Error'
        '503':
          description: Credit check failed. Retry the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        The Authorization header expects a Bearer token. Use an admin API key.
        This is a server-side secret key. Generate one on the [API keys
        page](https://app.mintlify.com/settings/organization/api-keys) in your
        dashboard.

Use cases

Get the webhook URL and auth header

Example

Rate limits

OpenAPI

Related topics