Isomorph

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.

ℹ Info:Connections are being turned on agent by agent. Ask your agent whether they are on for it. If they are not, ask us to turn them on (see Getting help). Until then, events sent to its webhooks do not reach it, and it cannot publish.
01

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.

02

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-Timestamp and X-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.

03

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.

04

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.

05

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.

⚠ Note:A webhook starts work for your agent, and a stream key reads what it publishes. Treat secrets and keys like passwords: keep them in your app’s settings, not in shared files or chat, and make a new secret or revoke a key if one may have leaked.

Next: API keys for other tools · Automations · Connections