Inbound agent HTTP signals
Endpoint:POST https://mcp.echozero.app/api/public/agent-signals/{agentId}
No developer API key. Authenticate with the per-agent signing secret (ezw_...) revealed once at provision or rotation.
Headers
Signing algorithm
- Serialize the request body as canonical JSON - keys sorted alphabetically at every object level,
undefinedfields omitted. - Build:
payloadString = "${unixSeconds}.${canonicalJson}" - Sign:
HMAC_SHA256(signingSecret, payloadString)→ lowercase hex
SDK helpers
The echozero-sdk providessignInboundWebhook / sign_inbound_webhook in TypeScript, Python, Go, and Rust with canonical JSON built in.
Replay protection
- Requests with timestamp skew beyond ±5 minutes are rejected with 401.
- Use a unique
idempotencyKeyper signal so retries are safe no-ops.
Sign or verify inbound (Python)
Only the signing-eligible keys count, so filter the body to them before you serialize. Two things must match the server’s JavaScript serializer. Text must be real characters, not\uXXXX escapes (ensure_ascii=False). Numbers must print the JavaScript way: 25, not 25.0, and 0.00002, not 2e-05. Python’s json.dumps gets both wrong by default, so use the js_json helper below.
pip install echozero, 0.2.0 or later) does this for you with sign_inbound_webhook.
Golden vectors: Signature test vectors.
Outbound execution webhooks
When your agent has awebhookUrl, EchoZero POSTs execution results after trade attempts.
Signing secret
Use the agent webhook signing secret configured on the agent (webhookUrl + secret pair). Rotate by updating the agent record in Dev Portal or PATCH /api/v1/agents/{id}.
Delivery contract
Event catalog
The public API spec does not define the fields inside
executionResult, so treat the ones above as an illustration. Build your handler on event, signalId, status and timestamp, and read other executionResult fields defensively. They can differ from the executionResult object returned by the inbound endpoint and the WebSocket gateway.Verify on your server
Headers:signalId deliveries as idempotent.
Provider webhooks (Telegram, Discord)
When EchoZero hosts signal ingestion for Telegram or Discord bots, provider-specific secrets apply. These routes do not use developer API keys.Telegram
Endpoint:POST /api/webhooks/telegram/signal-bot
When the server has SIGNAL_TELEGRAM_WEBHOOK_SECRET configured, every request must include:
setWebhook API.
Discord
Endpoint:POST /api/webhooks/discord/signal-bot
When SIGNAL_DISCORD_WEBHOOK_SECRET is set:
REST API HMAC (developer routes)
For authenticated developer API calls (/api/v1/*), HMAC uses your API secret with millisecond timestamps and method+path signing. See API keys and HMAC.
Security checklist
- Store signing secrets in a secrets manager - they are shown only once at creation/rotation.
- Use HTTPS for all webhook URLs.
- Enforce timestamp windows on every inbound webhook you receive.
- Deduplicate by
idempotencyKey(inbound) orsignalId(outbound). - Rotate compromised secrets via
rotateInboundWebhookSigningSecretor API key revocation in the Dev Portal.