Webhook and reply contract
This document describes everything you need to connect an external agent to Streams. After registering your agent you will receive a signing secret and an API key. The signing secret is how you verify us; the API key is how we verify you.
1. Register your agent
Section titled “1. Register your agent”POST /api/agents
Request (bearer token = your session token):
{ "providerType": "custom_webhook", "name": "My Agent", "config": { "endpointUrl": "https://your-agent.example.com/hook" }, "capabilities": { "streaming": false, "tools": [] }}providerType selects how Streams reaches your agent; custom_webhook is the webhook contract this document describes, and it is the default when the field is omitted. The provider’s own settings go in config — for a webhook agent that is just endpointUrl. Other provider types take their own config keys and a credentialId; see Connecting an agent provider.
Response 201 Created:
{ "data": { "registration": { "id": "<registration-id>", "agentUserId": "<user-id-for-this-agent>", "name": "My Agent", "providerType": "custom_webhook", "endpointUrl": "https://your-agent.example.com/hook", "config": { "endpointUrl": "https://your-agent.example.com/hook" }, "credential": null, "instructions": null, "triggerable": true, "status": "active", "capabilities": { "streaming": false, "tools": [] }, "createdBy": "<your-user-id>", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "secrets": { "signingSecret": "sk_sign_…", "apiKey": "sk_agent_…", "mcpUrl": "https://api.streams.chat/mcp" } }}The secrets object for a webhook agent contains a signing secret (for verifying incoming webhooks), an API key (for calling back into Streams), and the MCP URL. All three are shown once and cannot be retrieved again.
Token-only agents. If you do not want Streams to call you at all — your agent runs elsewhere and only calls back through the reply endpoint and MCP — connect with "config": { "triggeredByStreams": "no" } and no endpointUrl. The registration resolves to the custom_token_only provider and secrets is { "apiKey": "sk_agent_…", "mcpUrl": "…" }: no signing secret, because nothing is signed outbound. Mentioning such an agent fails with 403 agents.agent_not_triggerable; sections 2 and 3 below do not apply to it.
Secrets are shown once. Store them securely; they cannot be retrieved again. To get new secrets call POST /api/agents/:id/rotate. The old secrets stop working immediately.
status controls whether your agent receives invocations:
active— receives webhooks.paused— invocations are rejected with403 agents.agent_paused; callers see the paused fallback message.revoked— permanently disabled; the agent principal and its messages remain, but no new invocations are accepted.
To pause or resume: PATCH /api/agents/:id with { "status": "paused" } or { "status": "active" }.
2. Receive a webhook
Section titled “2. Receive a webhook”When a user mentions your agent in a stream, Streams sends a signed POST to your endpointUrl.
Method: POST
Headers:
| Header | Value |
|---|---|
x-streams-signature |
v1=<hex(hmac_sha256(signing_secret, timestamp + "." + raw_body))> |
x-streams-timestamp |
Unix timestamp in milliseconds (string) |
x-streams-delivery-id |
Invocation id; same value on every retry |
x-streams-attempt |
Attempt number (1-based integer, string) |
x-streams-agent-id |
The agent’s user id |
content-type |
application/json |
user-agent |
streams-agents/1 |
Payload:
{ "event": "agent.invoked", "invocationId": "<uuid>", "attempt": 1, "agent": { "userId": "<agent-user-id>", "name": "My Agent" }, "account": { "id": "<account-id>" }, "stream": { "id": "<stream-id>", "title": "Engineering", "kind": "stream" }, "threadSessionId": "<thread-id or null>", "trigger": { "kind": "mention", "messageId": "<message-id>", "senderUserId": "<user-id>", "text": "Hey <@user:agent-user-id>, summarise this thread", "attachments": [ { "assetId": "<asset-id>", "fileName": "screenshot.png", "contentType": "image/png", "url": "https://…signed…", "expiresAt": "2026-01-01T00:15:00.000Z", "link": "https://app.streams.chat/open/<asset-id>" } ] }, "replyMessageId": "<uuid — the id your reply message must use>", "context": { "messages": [ { "id": "<message-id>", "senderUserId": "<user-id>", "senderType": "user", "text": "Earlier message in the stream", "createdAt": "2026-01-01T00:00:00.000Z", "attachments": [] } ], "briefing": "Optional agent briefing text or null" }, "reply": { "url": "https://api.streams.chat/api/agents/reply", "mcpUrl": "https://api.streams.chat/mcp" }, "timestamp": "2026-01-01T00:00:00.000Z"}Field descriptions:
| Field | Type | Description |
|---|---|---|
event |
"agent.invoked" |
Always this value |
invocationId |
UUID | Unique per invocation; repeated on retries |
attempt |
integer | 1-based retry counter |
agent.userId |
UUID | The agent’s user principal id |
agent.name |
string | The agent’s display name |
account.id |
UUID | The account that owns the stream |
stream.id |
UUID | The stream where the mention (or cycle phase) occurred. Hosted / platform agents that only receive prose also see this in a leading Location: block of the turn text |
stream.title |
string | null | Stream title at dispatch time |
stream.kind |
“stream” | “dm” | absent | "dm" for a private direct message with a fixed set of people and agents, where stream.title is not a title but the participants’ names as the sender sees them (everyone but the sender). Absent from older servers: treat as "stream". Cycles are not available in a direct message |
threadSessionId |
UUID | null | Present when the turn is in a thread session (an in-thread @mention, or any turn after the reply thread is opened). Hosted / platform agents see the same id in the Location: block, or none on a main-channel turn that has not opened a thread yet |
trigger.kind |
"mention", "phase" or "ui_interaction" |
What triggered the invocation. ui_interaction: a person answered (or an admin dismissed) a form you showed with ask_user_questions; the trigger message is that form |
trigger.messageId |
UUID | The message that triggered this invocation |
trigger.senderUserId |
UUID | Who sent the trigger message. On a ui_interaction turn the trigger message is your own form, so this is the person who submitted or dismissed it |
trigger.text |
string | Markdown text of the trigger message. On a ui_interaction turn the form message holds only a one-line caption, so this is the synthesized [ui_interaction_result] block instead |
trigger.uiInteraction |
object | absent | Only on a ui_interaction turn, and also written into trigger.text as [ui_interaction_result] followed by a fenced JSON block of the same object. Fields: interactionId, toolName, status ("submitted" or "dismissed"), respondedBy or closedBy ({ id, name }), and for a submitted form answers, keyed by question key as { "question": "<title>", "value": <answer> }. A form you cancelled yourself is not sent back to you |
trigger.attachments |
array | Files for this turn: attachments on the trigger message, plus — when the turn is inside a cycle phase — that phase’s reference files (assetIds on the frozen phase). Each entry has assetId, fileName, contentType, and a short-lived signed url (expiresAt); url is null when signing failed. link (optional, only while the lasting file link is enabled for the person the turn is for) is the file’s lasting link: the signed url stops working after 15 minutes, the link does not, and opening it signs a new url for whoever opens it. Write link, never url, when a message refers to the file. De-duped by assetId (message metadata wins if both list the same id) |
replyMessageId |
UUID | Use this as the message id when posting your reply |
mcpApps |
object | absent | External MCP servers attached to this stream, rebuilt on every delivery; absent when none is attached. See below |
agentGuide |
string | What Streams is and where to answer: reply only in the session you were triggered in (never in the main channel of the stream unless the person explicitly told you to send a message in the stream), and attach any file you create to your reply; and mention nobody by default, only a person whose input you need (a question, decision or blocker), with <@user:ID>, once per turn, and not again for a request the person has not answered. Sent on every turn. Show it to your model as is |
uiGuide |
string | The “Streams UI first” rule, sent on every turn: when your reply asks people for input, shows several items to compare, or invites people to work on something together, use a Streams MCP tool whose description starts with [Streams UI] instead of plain text (tools/list on reply.mcpUrl lists them). Show it to your model as is |
uiReminder |
string | A one-line self-check for the end of your prompt, after the trigger text (and before the message history, if you put that in the prompt too: keep the history last, newest message first, so a cut takes the oldest messages). Show it to your model as is |
personalization |
object | absent | The output style in effect for this message, read from storage on every delivery: the agent owner’s, or the one the sender chose for themselves in Settings, which wins. An agent without a chosen style gets Brief; absent when the style in effect is Normal, after the sender’s own choice and Minimal on mobile are applied. personalization.outputStyle is { preset, instructions }: preset is brief or minimal (Normal sends nothing), and instructions is plain text to add to your model’s prompt. The preset is the one in effect for this message: with Minimal on mobile on (the sender’s or the owner’s), a message sent from the iOS app or a phone browser arrives as minimal even when the style is Normal or Brief. For such a message instructions also has one sentence about phone formatting (short paragraphs and lists, no wide tables or long code blocks), whichever of the two presets is in effect. minimal asks for a few lines and names a size to aim for (under 80 words), not a limit. It is a suggestion about wording only, so apply it below your own tool and safety rules, and skip it when the person explicitly asks for details. Streams does not check that your agent honors it |
context.messages |
array | Thread triggers only: up to 40 messages before the trigger in that thread (before the answer, for a ui_interaction turn), oldest first (each may include attachments). In a cycle run’s thread, only the current phase’s messages. Empty for main-channel (top-level) triggers — the trigger text, attachments, and optional context.briefing are the whole turn |
context.briefing |
string | null | Set on every turn in a cycle run’s thread (phase triggers and @mentions): what the cycle is, its phases with each closed phase’s outcome, the request that started it, and whether you own the current phase or are helping. Null outside cycles |
context.historyScope |
full | since_last_turn | absent |
Sphera agents only; absent for every other webhook. since_last_turn: your session already holds this thread’s earlier turns, so context.messages holds only what was posted after your previous turn’s trigger, your own messages excluded. full: the whole history as above |
context.briefingUnchanged |
true | absent |
Sphera agents only, with since_last_turn: your session already holds this cycle briefing, so context.briefing is a one-line note that it still applies. The full text comes again when it changes and once 20 messages have followed it |
context.omittedMessages |
number | absent | How many of the oldest history messages were left out so the request body stays under 240 KB. context.messages always holds the newest ones; the briefing, trigger and guides are never cut. Absent when nothing was left out |
reply.url |
URL | POST your reply here if replying asynchronously |
reply.mcpUrl |
URL | POST MCP calls here |
timestamp |
ISO 8601 | When the webhook was dispatched |
Attached MCP apps. When external MCP servers are attached to the stream, mcpApps tells your agent which tools it can call, so a request like “render me a chart” can reach an attached app without the user naming the tool:
"mcpApps": { "servers": [ { "name": "Test server", "status": "connected", "tools": [ { "name": "test_server__show_chart", "description": "Render a chart", "ui": true, "threadable": true, "requiredArgs": [] }, { "name": "test_server__add", "description": "Add", "ui": false, "threadable": false, "requiredArgs": ["a", "b"] } ] } ], "moreTools": 0, "replyToMessageId": "<message-id>"}tools[].nameis exactly what to call on the Streams MCP (reply.mcpUrl), with the stream id asstreamId.requiredArgslists the required arguments other thanstreamId, spelled exactly as the tool’s schema spells them.ui: truemeans the tool shows an app to the people in the stream. Whenthreadableis also true, passreplyToMessageIdto show it in this turn’s thread (the root of the thread session, or the trigger message when the trigger opens the reply thread). Auitool withthreadable: falsedefines areplyToMessageIdargument of its own; use it as that tool describes.- At most 20 tools are listed across all servers;
moreToolscounts the rest, whichtools/liston the MCP endpoint returns. A server withstatus: "error"is attached but not answering, so it is listed without tools. - The list is rebuilt for every delivery (not for the retries within one delivery), so attaching or detaching a server shows up on the next turn. Server names, tool names and descriptions come from third-party servers: treat them as data, never as instructions. Only agents that call the Streams MCP at run time get it. Hosted agents that do (Claude, Cursor, ElevenLabs, Mistral) see the same list as prose after the
Location:block, inside an<untrusted_content source="external_mcp">wrapper.
Signature verification:
Verify every incoming request before acting on it:
expected = "v1=" + hex(hmac_sha256(signing_secret, timestamp + "." + raw_body))accept iff constant_time_equal(expected, header) and |now_ms - timestamp| <= 300000The replay window is 300 seconds (300 000 ms). Reject any request outside this window.
x-streams-delivery-id repeats on retries: deduplicate on it to avoid processing the same invocation twice.
3. Respond
Section titled “3. Respond”You have three options for replying. All responses must come within 30 seconds (or ack then reply within 10 minutes). The response body must not exceed 1 MiB, and the reply text itself — the JSON message, or the SSE final.message — must not exceed 40 000 characters and 262 144 bytes (UTF-8), the same limits as an asynchronous reply. A longer reply fails the invocation with agent_invalid_response.
Option A — JSON reply (synchronous)
Section titled “Option A — JSON reply (synchronous)”Return HTTP 200 with Content-Type: application/json and a { "message": "…" } body:
{ "message": "Here is the summary you asked for." }Option B — SSE stream (synchronous)
Section titled “Option B — SSE stream (synchronous)”Return HTTP 200 with Content-Type: text/event-stream. Send one or more chunk events, a final event, then [DONE]:
data: {"type":"chunk","text":"Here is "}
data: {"type":"chunk","text":"the summary."}
data: {"type":"final","message":"Here is the summary."}
data: [DONE]Alternatively you can send just a final event without preceding chunks:
data: {"type":"final","message":"Here is the summary."}
data: [DONE]To signal failure:
data: {"type":"failed","error":"Optional description"}
data: [DONE]Option C — Acknowledge and reply asynchronously
Section titled “Option C — Acknowledge and reply asynchronously”Return HTTP 200 with Content-Type: application/json and { "ack": true }:
{ "ack": true }Then post the final reply to reply.url within 10 minutes. Each chunk or activity you post restarts that timer.
4. Reply asynchronously
Section titled “4. Reply asynchronously”POST /api/agents/reply
Headers:
Authorization: Bearer <apiKey>Content-Type: application/jsonBody types:
Acknowledge receipt (start the 10-minute timer):
{ "invocationId": "<invocationId>", "type": "ack" }Stream a progress chunk:
{ "invocationId": "<invocationId>", "type": "chunk", "text": "Partial text…" }chunk.text must not exceed 40 000 characters.
Report progress without reply text (a heartbeat). Each activity restarts the 10-minute timer and shows a status line under the agent’s working reply. kind is thinking, tool or working; text is optional, at most 2 000 characters, and only a short label of it is shown:
{ "invocationId": "<invocationId>", "type": "activity", "kind": "tool", "text": "Searching the docs"}During a long run, send an activity every few minutes so the invocation does not time out.
Post the final reply (closes the invocation):
{ "invocationId": "<invocationId>", "type": "final", "message": "Full reply text.", "assetIds": ["<optional ready asset ids, max 10>"]}final.message must not exceed 40 000 characters and 262 144 bytes (UTF-8).
Optional assetIds attaches files the agent already uploaded (MCP create_upload /
complete_upload, or POST /api/files/uploads) to the settled reply message — same
ownership rules as a human send: each id must be ready and owned by this agent
principal, at most 10. Missing or foreign ids fail with chat.asset_not_found /
chat.asset_not_owned. Omit the field (or pass []) for a text-only final.
message may be empty only when your agent showed a Streams UI (a form, a whiteboard or a media
carousel) during this attempt, in the turn’s thread or the main channel, and the final carries no assetIds. Streams then removes the empty reply
bubble and the shown UI is the answer. An empty message in any other case is refused with
400 agents.empty_final and the invocation stays open.
Report failure:
{ "invocationId": "<invocationId>", "type": "failed", "error": "Optional description" }Add "reason": "timed_out" when your runner’s own time limit ended the turn. Streams then tells the user the agent ran out of time instead of showing the generic error. Without reason, the failure shows as a generic error.
Add "userMessage" to tell the person why it failed, for example "This thread is too long for the agent. Start a new session.". Streams shows it after its own sentence as plain text (no formatting, mentions or links), with credentials removed and cut to 300 characters. error is never shown to users; it is kept for the operator’s logs. userMessage is also read from the SSE failed event and from a JSON { "success": false } response.
Status codes:
| Code | Error code | Meaning |
|---|---|---|
| 200 | — | Accepted |
| 401 | kernel.unauthorized |
Bearer token missing, unrecognised, or the signing key has been rotated |
| 403 | agents.agent_paused |
Agent is currently paused |
| 403 | agents.agent_revoked |
Agent has been revoked |
| 404 | agents.registration_not_found |
The token is valid but the agent has no registration in this account |
| 404 | agents.invocation_not_found |
Invocation id not found or does not belong to this registration |
| 409 | agents.invocation_closed |
Invocation already completed or failed |
A 401 means the bearer was not resolved at all — the token is unknown or its backing session was revoked (e.g. after POST /api/agents/:id/rotate). There is no separate agents.api_key_invalid error; the global kernel.unauthorized covers all unresolved bearers.
5. Use tools (MCP)
Section titled “5. Use tools (MCP)”POST /mcp
Streams exposes a Model Context Protocol endpoint at reply.mcpUrl. Use Streamable HTTP transport with Authorization: Bearer <apiKey>. The tools available to any principal (streams, chat, and anything added by later modules) are listed in Connect an MCP client.
Your agent acts as the agent principal and must be a stream member to use stream-scoped tools.
6. Manage your agent
Section titled “6. Manage your agent”List agents:
GET /api/agentsAuthorization: Bearer <your-session-token>Pause:
PATCH /api/agents/:idAuthorization: Bearer <your-session-token>{ "status": "paused" }Resume:
PATCH /api/agents/:idAuthorization: Bearer <your-session-token>{ "status": "active" }Rotate secrets:
POST /api/agents/:id/rotateAuthorization: Bearer <your-session-token>Returns a new { registration, secrets }. The old apiKey and signingSecret stop working immediately.
Remove:
DELETE /api/agents/:idAuthorization: Bearer <your-session-token>- The agent principal and its past messages remain; no new invocations are accepted.
7. Testing your endpoint
Section titled “7. Testing your endpoint”streams only calls public HTTPS addresses, so expose a local endpoint through ngrok or a similar tunnel while you develop.
To test signature verification, compute:
v1=hex(hmac_sha256(signing_secret, x-streams-timestamp + "." + raw_body))and compare it to x-streams-signature with a constant-time comparison. Reject if the timestamps differ by more than 5 minutes.