> For the complete documentation index, see [llms.txt](https://docs.rox.com/development/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rox.com/development/product/custom-agents/using-webhooks.md).

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

<figure><img src="/files/dSgZA7fLBP64tGDrVgqZ" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/FvYdQ2T5eNIiZHMe6KwJ" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/fLX6EuGisMr5jr6YiTLk" alt=""><figcaption></figcaption></figure>

**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:

```bash
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.**