Triggering a workflow with a webhook

A webhook lets an external system fire a CloudRadial AutomationAI workflow with an HTTP request, so another tool can start your automation the moment something happens on its side. This article is for Admins and Owners and covers enabling the webhook trigger, the generated URL and secret, rotating the secret safely, how the request payload reaches the workflow, and how a webhook differs from the Integration Key and from a playbook trigger URL.

Before you start, open the workflow you want to trigger in the Designer. The webhook is configured on that workflow, and your changes only take effect once you publish, so plan to publish after you enable it.

In this article:

• Enabling the webhook trigger
• The webhook URL and secret
• Rotating the webhook secret
• How the payload reaches the workflow
• Webhook vs. the Integration Key
• Playbook trigger secrets work differently

Enabling the Webhook Trigger

The webhook is the Start node's trigger, and you configure it from the workflow's Properties page.

1. Open the workflow in the Designer.
2. Select Properties, then find the Webhook section.
3. Turn on Enable webhook. This saves to the draft automatically.
4. Publish the workflow. The webhook only becomes active once a published version has it enabled.

Important -> Calls are checked against the published version of the workflow, not the draft. Until you publish a version with the webhook enabled, requests to the workflow's webhook URL return 404. The same applies in reverse: if you turn Enable webhook off, the published workflow keeps accepting calls until you publish again.

The Webhook URL and Secret

With the webhook enabled, AutomationAI shows a generated Webhook URL and a Secret, each with a Copy button.

• Callers must send the secret in the X-Crauto-Webhook-Secret request header. Requests without a matching header are rejected with 401.
• Use Regenerate to roll the secret. The new secret isn't active until you publish. See Rotating the Webhook Secret below.

Keep both the URL and the secret confidential. The section also provides a ready-to-run example request you can copy to test the trigger.

Rotating the Webhook Secret

The secret is part of the workflow definition, so a regenerated secret follows the same draft-then-publish cycle as every other change. The secret shown on the Properties page is the draft's secret. It only matches what callers need once you publish.

1. On the workflow's Properties page, select Regenerate next to the secret and confirm. The new secret is saved to the draft only.
2. Copy the new secret. The published workflow still accepts the current secret, so existing callers keep working.
3. Publish the workflow. From that moment, only the new secret is accepted.
4. Update every caller with the new secret right away. A caller still sending the old secret is rejected with 401.

Important -> There is no overlap window. The old secret stops working the instant you publish, and the new secret doesn't work until then. Plan the publish for a time when you can update your callers immediately, or when a few rejected calls won't cause problems.

Regenerating doesn't change the webhook URL. Only the secret changes.

How the Payload Reaches the Workflow

POST a JSON body to the webhook URL to fire the workflow. The body lands in the workflow as the trigger output, which your nodes read with binding expressions of the form {{ nodes.trigger.output.<field> }}.

For example, if the body contains an order id, it is available as {{ nodes.trigger.output.orderId }}. For the full data contract between nodes, see the article on passing data between nodes.

Webhook vs. the Integration Key

These two are easy to confuse, so here is the difference:

• A webhook secret is scoped to a single workflow and authenticates inbound requests to that workflow's trigger. It lives on the workflow's Properties page.
• The Integration Key is a static API key that ServiceAI uses to poll your workspace's webhook catalog. It lives under Settings > Integrations.

They are managed separately. For details on the Integration Key, see the article on connecting ServiceAI with an Integration Key.

Playbook Trigger Secrets Work Differently

A playbook that starts When something arrives also has a trigger URL authenticated by a secret in the X-Crauto-Webhook-Secret header, but that secret isn't versioned:

• Selecting Generate new secret on the playbook takes effect immediately. There's nothing to publish, and the previous secret stops working at once.
• The secret is shown only once, when you generate it. Copy it before you leave the page.
• One secret covers both the playbook's trigger URL and its signal URL, so update every caller of either URL.

If you are still having trouble, we're here to help! Submit a ticket for assistance, and don't forget to check our status page to ensure there are no outages in your area.