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 Connections.
Which one you need
- An app should tell your agent something (a new booking, a form, a paid invoice): an inbound endpoint, often called a webhook.
- A dashboard or app should show what your agent does, as it happens: a live stream key.
- Your app should receive each event at its own address: a push subscription.
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.
An app tells your agent (a webhook)
Under Inbound endpoints, give the endpoint 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:
- Signed requests (recommended): 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). - A fixed token in a header: your app sends
Authorization: Bearer <secret>, for apps that cannot sign.
Press Add endpoint and copy the secret. The endpoint’s address 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 endpoint’s own thread. If your agent is busy or restarting, the event waits and is tried again for up to 24 hours.
Each endpoint 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 What your agent may publish, 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.
A live stream for a dashboard
Under Live stream keys, 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.
Push events to your app
Under Push subscriptions, enter Your app’s address (https) and, if you like, Only these event types. Press Add subscription 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