Skip to content
BrainRoad BrainRoad
Documentation Menu

Webhooks Overview

Let external services send events to your agent via webhooks.

On this page

What Are Webhooks?

Webhooks are HTTP callbacks. When something happens in an external service, that service sends an HTTP request to a URL you specify. Your agent receives that request and can act on it immediately.

Instead of your agent polling a service every few minutes to check for updates, the service pushes events to your agent the moment they happen. This makes your agent reactive and fast.

What Can Trigger a Webhook?

Almost any external service that supports webhooks can push events to your agent. Common use cases include:

  • Form submissions — A visitor fills out a contact form on your website. The form service sends the submission to your agent, which drafts and sends a personalized response.
  • Payment notifications — Stripe, PayPal, or your payment processor fires a webhook when a customer pays. Your agent logs the transaction or sends a confirmation.
  • Calendar events — Google Calendar or Calendly sends a notification when a meeting is booked. Your agent prepares a briefing or sends a reminder.
  • CI/CD triggers — GitHub or GitLab pushes a webhook on code events. Your agent can summarize pull requests or flag failed builds.
  • CRM updates — HubSpot or Salesforce notifies your agent when a lead status changes.

How Your Agent Processes Webhooks

When a webhook event hits your agent’s endpoint, the agent receives the raw HTTP payload. It reads the event type and data, then decides what to do based on its configuration and context. The agent can parse JSON bodies, extract relevant fields, and take follow-up actions like sending a message, updating a file, or kicking off a multi-step workflow.

Webhooks run through the same isolated environment as everything else your agent does. No other user’s agent can see your webhook traffic.

Built-In Inbound Channels

In addition to generic webhooks, BrainRoad has built-in webhook receivers for specific services. These process incoming messages and surface them as activity events automatically:

  • Inbound email (Mailgun) — When someone replies to an email your agent sent via Mailgun, the reply is received via webhook and appears in your agent’s activity feed. This means your agent can have email conversations without polling an inbox. See Email Setup for configuration.
  • Inbound SMS (Twilio) — Text message replies arrive via Twilio webhook and appear as activity events. Your agent can receive and respond to SMS messages. Requires a Twilio phone number configured to forward to your agent’s SMS webhook URL.

Both channels validate incoming webhook signatures to prevent spoofing.