Skip to content
Hyponema Hyponema Docs

Streaming and events

Hyponema integrations can involve streaming assistant output, voice connections, and outbound notifications. Exact event names and payloads should come from the current API tab or official workspace reference.

Text streaming

Section titled “Text streaming”

For text chat, your backend sends the User message and consumes a stream of assistant progress. The application should render partial output carefully, handle final completion, and surface errors without exposing secrets.

Voice connections

Section titled “Voice connections”

For voice clients, the backend should prepare the session and give the client a signed connection value. The client should handle microphone permissions, network interruptions, mute state, and disconnect behavior.

Webhooks

Section titled “Webhooks”

When using outbound webhooks:

  • Use HTTPS endpoints.
  • Verify signatures before trusting a payload.
  • Make handlers idempotent.
  • Return success only after durable processing or queueing.
  • Rotate secrets when ownership changes.

Delivery is at-least-once

Section titled “Delivery is at-least-once”

Webhook delivery is at-least-once: a single event can be delivered more than once. Retries after a non-2xx response, and crash-driven redelivery, can repeat the same event. Receivers must deduplicate.

  • Deduplicate on the event id. Every delivery carries the X-Hyponema-Event-Id header — a stable UUID that is reused across retries and crash-driven redelivery of the same event. The same id also appears as the top-level event_id field in the body. Treat a repeated id as already-processed.
  • The X-Hyponema-Event-Type header carries the event type, and the X-Hyponema-Delivery-Attempt header carries the per-delivery attempt number that distinguishes retries of the same event; neither changes the dedupe key.
  • Acknowledge fast and process asynchronously. A slow or failed acknowledgement can trigger a retry even when your handler already succeeded.

Trusted backends need an explicit webhooks:admin grant to manage outbound webhook endpoints, review delivery history, or rotate signing secrets. The dashboard remains the place to copy one-time secrets safely, review access, and coordinate key rotation with your team.