Webhooks & event surfaces

Indexed catalog of every public event surface: webhooks, SSE streams, and polling endpoints.

Guides/Integration

YieldFabric exposes events to clients through three different mechanisms — HTTP webhooks, Server-Sent Events (SSE), and a polling REST surface. This page indexes all of them in one place.

Webhooks (server → your URL)

Inbound HTTP callbacks YieldFabric sends to a URL you register.

Webhook
POST /webhooks/sumsub
Service
auth
Auth
HMAC over request body
Use case
KYC outcome from Sumsub provider
Spec

That's the entire webhook surface today. Sumsub is Phase 2 — not enabled by default in shipped deployments; the endpoint exists for when an operator turns Sumsub on as a KYC provider.

No outbound webhooks for payment-domain events (deposits, payment completion, deal-flow state changes). Use SSE or polling instead — see below.

Server-Sent Events (SSE) — server-pushed event streams

For real-time event delivery, YieldFabric publishes SSE streams. The client opens a long-lived HTTP connection and the server pushes event: / data: frames as state changes.

Agents service SSE surfaces

These are the public stream routes available to applications:

Stream
Working-group chat stream
Endpoint
GET /working-groups/{id}/chat/stream
Triggers
New chat messages, agent responses, typing indicators
Spec
Stream
Working-group workflow stream
Endpoint
GET /working-groups/{id}/workflows/{wid}/stream
Triggers
Workflow step start / complete / fail; final outcome
Spec
Stream
Working-group audit events
Endpoint
GET /working-groups/{id}/audit-events
Triggers
Member add/remove, permission grants, configuration changes
Spec
Stream
Pipeline events
Endpoint
GET /pipelines/{run_id}/events
Triggers
Pipeline step progress, KG mutation, intent confirmation prompt
Spec

All four are working-group-scoped (or pipeline-scoped); there is no unscoped /threads/{id}/events or /workflows/{id}/events route — threads / workflows live under their parent working group.

Full event taxonomy (event names, payload shapes, retry semantics) is in .

No SSE in auth or payments today

  • auth has no SSE surface — auth events (login, key rotation, lockdown) are recorded in the audit log; query via the relevant endpoint.
  • payments has no SSE surface — message-state changes are polled via the Messages REST surface (see below).

Polling (REST queries the client repeats)

For server state the client cares about that isn't pushed via SSE, use polling.

Payments: message state

Endpoint
GET /api/users/{user_id}/messages
Returns
Messages with optional filters (message_type, status, chain_id, date range)
Spec
Endpoint
GET /api/users/{user_id}/messages/{message_id}
Returns
Single message
Spec
same
Endpoint
GET /api/users/{user_id}/messages/summary
Returns
Roll-up counts (pending / executing / completed / failed / retrying)
Spec
same
Endpoint
GET /api/users/{user_id}/messages/history
Returns
Status-change timeline
Spec
same
Endpoint
GET /api/users/{user_id}/messages/status/{status}
Returns
Filtered by status
Spec
same
Endpoint
GET /api/users/{user_id}/messages/type/{message_type}
Returns
Filtered by type
Spec
same

Polling cadence: for a freshly submitted Automatic-mode message, poll every 1-2s for up to 30s; for Manual-mode messages (waiting on user signature), poll less frequently (every 5-10s) or wait for the wallet UX to indicate completion.

Auth: verification + login key status

Endpoint
GET /auth/verifications/me
Returns
KYC verification records for the current user
Spec
Endpoint
GET /auth/users/me/lockdown
Returns
Account lockdown status (none / pending / cooldown_expired / executed)
Spec
Endpoint
GET /auth/users/me/login-keys
Returns
Public keys that can sign you in
Spec

Federated GraphQL subscriptions

Apollo Router supports GraphQL subscriptions but they're not configured today for YieldFabric subgraphs. Real-time channels that would naturally be subscriptions (deal state changes, payment completion) ship as SSE streams on the agents service (for deal flow) or polling on the payments side (for payment status).

If a future release adds GraphQL subscriptions, this page should be updated to reflect the new transport.

Authentication on event channels

All event surfaces (webhook callbacks, SSE streams, polling endpoints) use the same JWT as the rest of the API. The only exception is the Sumsub webhook, which uses HMAC over the body (because the caller is the Sumsub service, not your client).

For SSE specifically: pass the JWT in the Authorization header on the initial GET request. The stream stays authenticated for the life of the connection.

Reliability semantics

Surface
Sumsub webhook
Delivery guarantee
At-least-once (Sumsub retries on non-2xx)
What happens on failure
Idempotency-safe: re-receiving the same outcome is a no-op
Surface
SSE streams
Delivery guarantee
Best-effort — events delivered while the connection is open
What happens on failure
Reconnect and replay missed state via the polling endpoint
Surface
Polling
Delivery guarantee
Last-write-wins
What happens on failure
Query again

There is no event log replay for SSE-only events. If a client needs guaranteed delivery, it must either:

  1. Maintain an open SSE connection and reconnect promptly on drop, or
  2. Poll the underlying state endpoint as a backstop.

Most client flows do both — SSE for the "live" experience, polling on reconnect for catch-up.

Future webhook surface (not implemented)

If outbound payment-domain webhooks become a requirement, the natural pattern would be:

  • POST /webhooks/payments/{event_type} on a customer-supplied URL, signed with HMAC over the body.
  • Event types matching the MessageStatus state-machine transitions (e.g. message.executed, message.failed).
  • A per-customer webhook config endpoint to register URLs + rotate HMAC secrets.

None of this exists today. Don't write client code that depends on outbound payment webhooks.

See also

Back to all guides
YieldFabric docs(317)