Skip to content
BrainRoad BrainRoad
Documentation Menu

Setting Up Webhooks

Configure webhook endpoints for your agent to receive external events.

On this page

Your Agent’s Webhook URL

Each agent has a unique webhook endpoint. You provide this URL to external services so they know where to send events. The URL routes through BrainRoad’s infrastructure directly to your isolated agent container.

You can find your agent’s webhook URL on the agent detail page in the dashboard under the Webhooks section.

Configuring an External Service

The general process is the same across most services:

  1. Copy your agent’s webhook URL from the dashboard.
  2. Open the external service’s webhook or integration settings.
  3. Paste the URL into the webhook endpoint field.
  4. Select which events should trigger the webhook (e.g., “new form submission” or “payment completed”).
  5. Save the configuration.

The external service will now send HTTP POST requests to your agent whenever the selected events occur.

Testing Webhooks

Most services include a “Send Test Event” button in their webhook settings. Use it. After sending a test event, check your agent’s Activity tab to confirm the event arrived and was processed.

If the test event does not appear, verify the webhook URL is correct and that your agent is running. A stopped agent cannot receive webhooks.

Common Webhook Sources

Services that work well with agent webhooks include Stripe, GitHub, Calendly, Typeform, Zapier, Make (Integromat), Slack, and most CRM platforms. Any service that can send an HTTP POST to a URL can send events to your agent.

Payload Format

Your agent accepts JSON payloads. Most modern services send JSON by default. If a service sends form-encoded data, the agent can still parse it, but JSON is preferred for structured event handling.

Webhook Security

Each webhook URL includes a unique token that authenticates requests to your agent. You can regenerate this token from the dashboard if you need to revoke access — any previously configured services will stop being able to send events until you update them with the new URL.

For developers using the Public API, webhook details are also available programmatically:

  • GET /api/agents/:id/webhook — retrieve your webhook URL and token
  • POST /api/agents/:id/webhook/regenerate — generate a new webhook token
  • Webhooks Overview — what webhooks are and how your agent uses them
  • Reading Logs — verify webhook events are arriving in the Activity feed
  • Common Issues — troubleshoot if webhook events are not appearing