Using webhooks

Sometimes the moment that should trigger an agent does not begin in Rox.

It begins in a form submission. A signup event. An internal tool. A system somewhere else in your stack.

That is where webhooks come in.

Webhook-triggered agents let an external system start an agent in Rox. Once the webhook arrives, Rox reads the payload, understands the event, and takes the right next step.

That might mean:

• routing a signup

• sending an alert

• generating a summary

• updating a record

• launching an internal process

• triggering downstream work from another system

How to use a webhook trigger

Step 1

Choose On Webhook Call as the trigger when building the agent.

Step 2

Copy the webhook URL or slug from the agent UI.

Webhook URLs are generated in the UI now, so most users do not need to hand-assemble the endpoint.

If you need to support authentication, check the Use auth option and a signing key will one-time appear to set in the header.

Step 3

Send a POST request with JSON data to the webhook endpoint.

For new custom agents, use the URL generated in the UI. It follows the shared webhook pattern:

curl -X POST https://.../webhooks/w/{webhook_slug} \
  -H "Content-Type: application/json" \
  -d '{"feedback":"here's some feedback"}'

curl -X POST https://.../webhooks/w/{webhook_slug} \
  -H "Content-Type: application/json" \
  -d '{"feedback":"here's some feedback"}'

curl -X POST https://.../webhooks/w/{webhook_slug} \
  -H "Content-Type: application/json" \
  -d '{"feedback":"here's some feedback"}'

Step 4

Use the payload inside the agent.

The payload can be any JSON object. That data can then be read and used in later steps.

When to use webhooks

Use a webhook-triggered agent when Rox should respond to an external event.

Examples:

• Google Form submission

• marketing signup

• internal tool event

• external system update

• custom automation from another platform

A webhook is the outside world tapping Rox on the shoulder and saying:

This happened. Take it from here.