Webhooks and live events
Your own apps and your agent can tell each other when something happens. An app calls your agent at a webhook address, and your agent publishes events that your apps follow live or receive at their own address. You set this up on the agent’s Access page, under Webhooks and integrations. New to this? Start with the step-by-step Connect your other apps guide, with Zapier, Make and n8n examples.
Which one you need
- An app should tell your agent something (a new booking, a form, a paid invoice): an incoming webhook.
- A dashboard or app should show what your agent does, as it happens: a event stream with an API key.
- Your app should receive each event at its own address: a outgoing webhook.
Owners and admins add and change these. Everyone else with access to the agent sees them. Every secret and key is shown once, right after you create it: copy it straight into your app.
Incoming webhook: an app tells your agent
Under Incoming webhook, give the webhook a Name (for example new-booking) and write what your agent should do in When this fires, your agent should…, for example “Add the booking to my calendar and tell me in the morning summary.”
Then choose How your app proves it’s yours:
- Signing secret (recommended when your app supports it): your app signs each request with the secret, in the headers
X-Signature-TimestampandX-Signature(HMAC-SHA256 of the timestamp, a dot, and the body). - Bearer token: your app sends
Authorization: Bearer <secret>, for apps that cannot sign.
Press Create incoming webhook and copy the secret. The Webhook URL is listed with it: paste it into your app’s webhook settings. Your app sends a JSON body; the address answers at once, and your agent starts a task with your instruction and what the app sent, in that webhook’s own topic. If your agent is busy or restarting, the event waits and is tried again for up to 24 hours.
Each webhook has a Delivery log, New secret (the old one keeps working for 24 hours, so you can update your app), Pause and Delete.
Your agent tells your apps (events it publishes)
Your agent can publish an event when something happens in its work, such as deal.won or report.ready, with the details your app needs. Ask for it in plain words: “When you finish a client report, publish report.ready with the client’s name and the link.”
Under Events your agent may send, list the event types it may send: deal.created, deal.* for a family, or * for anything. It cannot publish a type that is not on the list, and keys and passwords are removed from what it sends.
Event stream (API key): a dashboard follows your agent
Under Event stream (API key), name the key after the app that uses it (for example “Sales dashboard”) and choose What the app may do:
- Watch live: the app follows the stream address and receives each event as it is published (server-sent events).
- Catch up on past events: the app reads the catch-up address, a page at a time, from where it last stopped. Events are kept for 7 days, so an app that was offline for less than that misses nothing.
You can limit a key to Only these event types and choose when it Expires after (30 days to a year). The app sends the key as Authorization: Bearer <key>. Both addresses are shown above the keys. Revoke a key and it stops working.
Outgoing webhook: your agent tells your app
Under Outgoing webhook, enter The other app’s webhook URL (https) and, if you like, Only these event types. Press Add outgoing webhook and copy the signing secret.
Each event your agent publishes is sent to that address as it happens, as JSON, signed the same way as a webhook (X-Signature-Timestamp and X-Signature), so your app can check it really came from your agent. If your app does not answer, the event is tried again for about half an hour, and the person who added the subscription is told if it still cannot be delivered. The Delivery log shows what was sent.
Next: API keys for other tools · Automations · Connections