DAdagucloud
webhooks

Trigger DAG execution via webhook

Changed on

Triggers a DAG execution via webhook. The DAG must have a webhook configured and enabled. Authentication depends on the webhook auth mode: bearer token only, bearer token plus HMAC, or HMAC only.

The request body is passed to the DAG as the WEBHOOK_PAYLOAD environment variable, and as a file named by WEBHOOK_PAYLOAD_FILE. A body too large for one environment variable is passed only as the file. If the DAG configures webhook.forward_headers, selected request headers are passed as the WEBHOOK_HEADERS environment variable. For safety, the Authorization header is never forwarded. The DAG run is enqueued and the endpoint returns immediately with the dag-run ID.

post/webhooks/{fileName}

Request

  • Base URL
    http://localhost/api/v1
  • Auth
    none required

Path parameters

fileNamestring regex required

Name of the DAG file

the name of the DAG file

Query parameters

remoteNodestring

name of the remote node

Headers

Authorizationstring

Bearer token for webhook authentication (e.g., 'Bearer dagu_wh_...'). Accepts the webhook's default token or one of its profile tokens. Required only when the webhook auth mode includes token authentication.

X-Dagu-Signaturestring
Example:sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

HMAC webhook signature in the format sha256=<hex>. Required only when the webhook auth mode includes HMAC authentication with strict enforcement. Sign the raw request body when X-Dagu-Profile is absent. When it is present, sign x-dagu-profile:<profile>\n<raw-request-body>.

X-Dagu-Profilestring

Runtime profile name.

Runtime profile selected for this DAG run. With the default token, the profile must be allowed by the webhook profile-selection policy; omit the header to use the DAG's default profile resolution. With a profile token, the run always uses the token's profile; the header may be omitted or must name that profile.

Request body

dagRunIdstring

Optional idempotency key. If provided and a DAG run with this ID already exists, the endpoint returns 409 Conflict. If not provided, a new UUID is generated.

payloadobject

Arbitrary JSON payload to pass to the DAG as WEBHOOK_PAYLOAD

Example request

{
  "dagRunId": "latest"
}

Response

DAG run triggered successfully

dagRunIdstring required

Unique identifier for the DAG-run. The special value 'latest' can be used to reference the most recent DAG-run.

dagNamestring required

Name of the triggered DAG

Example response

{
  "dagRunId": "latest"
}

Changes

  • v18d56f368c05aRevision changes
    • info

      added the new optional header request parameter X-Dagu-Profile

  • v175b8e91aaf57Revision changes
    • warning

      added the new conflict enum value to the response property for the response status

    • warning

      added the new conflict enum value to the response property for the response status

    • warning

      added the new conflict enum value to the response property for the response status

    • warning

      added the new conflict enum value to the response property for the response status

    • warning

      added the new conflict enum value to the response property for the response status

    • warning

      added the new conflict enum value to the response property for the response status

    • warning

      added the new human_task_resume_failed enum value to the response property for the response status

    • warning

      added the new human_task_resume_failed enum value to the response property for the response status

    • warning

      added the new human_task_resume_failed enum value to the response property for the response status

    • warning

      added the new human_task_resume_failed enum value to the response property for the response status

    • warning

      added the new human_task_resume_failed enum value to the response property for the response status

    • warning

      added the new human_task_resume_failed enum value to the response property for the response status

    • warning

      added the new payload_too_large enum value to the response property for the response status

    • warning

      added the new payload_too_large enum value to the response property for the response status

    • warning

      added the new payload_too_large enum value to the response property for the response status

    • warning

      added the new payload_too_large enum value to the response property for the response status

    • warning

      added the new payload_too_large enum value to the response property for the response status

    • warning

      added the new payload_too_large enum value to the response property for the response status