API Coming Soon: The webhook API endpoints will be available in the next release. For now, you can create and manage webhooks through the Roe UI.
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
- Create a webhook at the organization level with a name and destination URL
- Link the webhook to one or more agents
- Run agent jobs as usual via the UI, API, or VolansDB
- Receive payloads at your URL when jobs complete (success or failure)
Creating Webhooks
You can create webhooks via the API 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 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: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 a400 Bad Request error.
To delete a webhook:
- First, unlink all agents from the webhook using the Unlink Agent endpoint
- Then delete the webhook using the Delete Webhook endpoint