> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roe-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time notifications when agent jobs complete

Webhooks allow you to receive HTTP notifications when your agent jobs complete. Instead of polling for job status, configure a webhook URL and Roe will automatically send the job results to your endpoint.

## Use Cases

* **Real-time data pipelines**: Trigger downstream processing as soon as agent jobs finish
* **Notifications**: Send alerts to Slack, email, or other services when jobs complete
* **Database updates**: Automatically store extracted data in your systems
* **Workflow automation**: Chain agent outputs into other processes

## How Webhooks Work

1. **Create a webhook** at the organization level with a name and destination URL
2. **Link the webhook** to one or more agents
3. **Run agent jobs** as usual via the UI, API, or SQL workspace
4. **Receive payloads** at your URL when jobs complete (success or failure)

## Creating Webhooks

You can create webhooks via the [API](/api-reference/webhooks/create-webhook) or the Roe UI.

A webhook requires:

* **Name**: The name to reference
* **URL**: The endpoint that will receive POST requests

## Linking Webhooks to Agents

After creating a webhook, link it to one or more agents. When any linked agent completes a job, the webhook will fire.

You can link agents via the [API](/api-reference/webhooks/link-agents) or the dashboard.

### Testing Webhooks

Before going live, you can test that your webhook endpoint is correctly configured. Send a test payload to verify your endpoint receives and processes the webhook correctly.

To test a webhook linked to an agent, use the test endpoint:

```bash theme={null}
POST /v1/agents/{agent_id}/webhooks/{webhook_id}/test/
```

This sends a sample payload to your webhook URL so you can verify connectivity and response handling without running an actual agent job.

## Webhook Payload

When an agent job completes, Roe sends a POST request to your webhook URL with a JSON payload.

### Payload Fields

| Field                | Description                                                                         |
| -------------------- | ----------------------------------------------------------------------------------- |
| `timestamp`          | ISO 8601 timestamp when the webhook was sent                                        |
| `agent.id`           | UUID of the base agent                                                              |
| `agent.name`         | Name of the agent                                                                   |
| `agent_version.id`   | UUID of the specific agent version that ran                                         |
| `agent_version.name` | Version name (e.g., "v1")                                                           |
| `job.id`             | UUID of the completed job                                                           |
| `job.status`         | Either `"succeeded"` or `"failed"`                                                  |
| `job.status_code`    | Numeric status code                                                                 |
| `job.cost`           | Cost of the job in USD                                                              |
| `job.created_at`     | When the job was created                                                            |
| `job.completed_at`   | When the job finished                                                               |
| `job.output`         | The extracted data from the agent (structure depends on your agent's output schema) |
| `job.metadata`       | Any metadata attached to the job                                                    |
| `organization.id`    | UUID of the organization                                                            |
| `organization.name`  | Name of the organization                                                            |

## Deleting Webhooks

Webhooks are protected from accidental deletion. If a webhook is still linked to one or more agents, the delete operation will fail with a `400 Bad Request` error.

To delete a webhook:

1. First, unlink all agents from the webhook using the [Unlink Agent](/api-reference/webhooks/unlink-agent) endpoint
2. Then delete the webhook using the [Delete Webhook](/api-reference/webhooks/delete-webhook) endpoint

## API Reference

<CardGroup cols={2}>
  <Card title="List Webhooks" icon="list" href="/api-reference/webhooks/list-webhooks">
    Get all webhooks in your organization
  </Card>

  <Card title="Create Webhook" icon="plus" href="/api-reference/webhooks/create-webhook">
    Create a new webhook
  </Card>

  <Card title="Link Agents" icon="link" href="/api-reference/webhooks/link-agents">
    Connect agents to a webhook
  </Card>

  <Card title="Delete Webhook" icon="trash" href="/api-reference/webhooks/delete-webhook">
    Remove a webhook
  </Card>
</CardGroup>