SyntrumDocs
Open app

Webhooks

Webhooks connect your agents to the outside world with real-time inbound events. Where an integration is your agent reaching out to a system, a webhook is an external system reaching in: when something happens on their side, they send a request to your agent's endpoint, and the agent responds.

Webhooks are coming soon. Open Webhooks in the sidebar to see the live preview and the expected launch window. This page describes the model and how to prepare; the endpoint and setup surface light up when the feature ships.

The request/response model#

A webhook is a duplex exchange between an external service and your agent:

  1. Request in. The external service sends an HTTP POST to your agent's webhook URL, carrying a custom payload — the event data (the order, the ticket, the alert).
  2. Verify. The request's signature is checked before anything runs, so only trusted senders reach the agent.
  3. Act. The agent receives the event and works it through its normal loop and guardrails.
  4. Response out. The endpoint returns a response (a 200 OK on success), so the sender knows the event was received.

Announced capabilities: real-time events, secure signatures, custom payloads, and API endpoints.

Setup (what to expect)#

When webhooks ship, wiring one up will follow this shape:

  1. Create an inbound endpoint for the agent that should receive the events — this is the URL you give the external service.
  2. Copy the signing secret so you can verify that incoming requests are genuinely from that service.
  3. Register the URL in the sending system and choose which events it should POST.
  4. Map the payload to what the agent should do with it.
  5. Send a test event and confirm you get a 200 OK back.

Security#

Treat your webhook URL and signing secret like credentials. Anyone who can reach the endpoint can hand your agent work, which is why signature verification is the model's first line of defense — requests that don't carry a valid signature are rejected before the agent ever sees them. Keep the secret out of client-side code and rotate it if it leaks.

Beyond signatures, the same safety net applies as everywhere else:

A webhook can deliver an event, but it can't grant an agent new powers. Whatever the agent does in response still resolves through the three-plane cascade — the workspace floor, the agent's supervision mode, and each tool's permission. An inbound event that leads to a sensitive action still parks for your approval.

Webhooks vs. triggers#

They're two ends of the same idea:

Direction Who initiates
Triggers A connected tool's event → your agent Syntrum watches the tool
Webhooks Any external system → your agent The external system calls you

Use a trigger when the source is a tool you've already connected; use a webhook when you want an arbitrary external service to push events into an agent directly.

What to prepare now#

  1. Decide which agent should own the inbound events, and shape it with Templates.
  2. Confirm the external system can send outbound webhooks and sign them.
  3. Review your guardrails so agent responses to inbound events are governed the way you want.

What's next#