Skip to content

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.


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 with 403 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" }.


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[].name is exactly what to call on the Streams MCP (reply.mcpUrl), with the stream id as streamId. requiredArgs lists the required arguments other than streamId, spelled exactly as the tool’s schema spells them.
  • ui: true means the tool shows an app to the people in the stream. When threadable is also true, pass replyToMessageId to show it in this turn’s thread (the root of the thread session, or the trigger message when the trigger opens the reply thread). A ui tool with threadable: false defines a replyToMessageId argument of its own; use it as that tool describes.
  • At most 20 tools are listed across all servers; moreTools counts the rest, which tools/list on the MCP endpoint returns. A server with status: "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| <= 300000

The 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.


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.

Return HTTP 200 with Content-Type: application/json and a { "message": "…" } body:

{ "message": "Here is the summary you asked for." }

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.


POST /api/agents/reply

Headers:

Authorization: Bearer <apiKey>
Content-Type: application/json

Body 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.


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.


List agents:

GET /api/agents
Authorization: Bearer <your-session-token>

Pause:

PATCH /api/agents/:id
Authorization: Bearer <your-session-token>
{ "status": "paused" }

Resume:

PATCH /api/agents/:id
Authorization: Bearer <your-session-token>
{ "status": "active" }

Rotate secrets:

POST /api/agents/:id/rotate
Authorization: Bearer <your-session-token>

Returns a new { registration, secrets }. The old apiKey and signingSecret stop working immediately.

Remove:

DELETE /api/agents/:id
Authorization: Bearer <your-session-token>
  1. The agent principal and its past messages remain; no new invocations are accepted.

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.