Webhook callbacks

When you trigger a flow with the Flows API, GitLab can send the flow lifecycle events to a webhook that you specify. You can then react when the flow starts, finishes, or fails, instead of polling the API for the flow status.

You can use webhooks in a project or a group. Child projects inherit webhooks. This means that a webhook on a top-level group serves the flows of every project in that group.

Prerequisites

For a webhook to receive flow events, ensure the following prerequisites are met:

• A webhook has been created for the project or group, and callbacks are turned on for it.
• The webhook belongs to the project or group the flow runs in, or to one of the ancestor groups of that project or group.
• The webhook is not a system webhook.

Turn on callbacks for a webhook

Prerequisites:

• For project webhooks, you must have the Maintainer or Owner role for the project.
• For group webhooks, you must have the Owner role for the group.

To turn on callbacks for a webhook:

1. In the top bar, select Search or go to and find your project or group.
2. In the left sidebar, select Settings > Webhooks.
3. Select Add new webhook, or select Edit for an existing webhook.
4. Under GitLab Duo Agent Platform, select the Send Duo flow events to this webhook checkbox.
5. Select Add webhook or Save changes.

You can also set the duo_flow_callback_enabled attribute with the project webhooks API or the group webhooks API. Use either API to list the webhooks and find the ID of the webhook you turned callbacks on for.

The roles required to turn callbacks on apply only to the webhook. A user who triggers a flow that references the webhook does not need them.

Receive callbacks for a flow

Prerequisites:

• You must meet the prerequisites for flows.

To receive callbacks, pass the webhook ID as the callback_hook_id attribute when you trigger a flow:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "project_id": "5",
    "goal": "Fix the failing pipeline by correcting the syntax error in .gitlab-ci.yml",
    "workflow_definition": "developer/v1",
    "start_workflow": true,
    "callback_hook_id": 42,
    "client_reference": "run-abc123"
  }' \
  --url "https://gitlab.example.com/api/v4/ai/duo_workflows/workflows"

For the events GitLab sends and the structure of each payload, see GitLab Duo flow events.

Correlate callbacks with a request

Use the optional client_reference attribute to correlate callbacks with the request that triggered the flow. GitLab echoes the value back in every callback for that flow and does not interpret it.

Handling callbacks in your endpoint

Verify that a callback came from GitLab before you act on it. Callbacks carry the same headers as every other webhook event, so configure a signing token on the webhook and verify the signature.

GitLab can deliver the same event more than once, so make your endpoint idempotent. If your endpoint does not return a success or redirect response, GitLab retries the delivery up to five times with a backoff. Retries repeat the event_id from the original payload, so store the event_id values you have processed and ignore an event you have already seen. After the retries are exhausted, GitLab stops trying to deliver that event.

Repeated delivery failures count towards the webhook failure limits, and GitLab can automatically disable the webhook. When a webhook is temporarily disabled, GitLab holds the flow events for that webhook and delivers them after the disabled period ends. GitLab holds an event a maximum of three times. If the webhook is still disabled, GitLab does not deliver the event. GitLab sends no flow events to a permanently disabled webhook. To receive flow events again, re-enable the webhook.

Before every delivery attempt, GitLab verifies that callbacks are still turned on for the webhook. If you turn callbacks off while a flow is running, GitLab stops sending events for that flow, including queued events and pending retries.

To see what GitLab sent and what your endpoint returned, view the webhook request history. The Recent events section displays all requests made to a webhook in the last two days. This section displays only delivery attempts, so it does not include events that GitLab held or did not deliver while the webhook was disabled.

Related topics

• GitLab Duo flow events
• Flows API
• Webhooks