Webhooks

Webhooks let Hyponema notify your system about events outside the request that caused them.

Delivery model

Hyponema signs outbound webhook requests with HMAC-SHA256 and retries failed deliveries with exponential backoff.

Delivery is at most once per (tenant_id, event_id) queue entry. Retries for the same event are tracked by attempt number so repeated worker runs do not duplicate attempts.

Endpoint health

Endpoints can be automatically disabled after repeated failures and a long window without success. Monitor delivery attempts during beta rollout.

Receiver checklist

Verify the HMAC signature before processing.
Make handlers idempotent using the event ID.
Return a 2xx response only after durable acceptance.
Keep processing fast; offload long work to your own queue.
Alert on repeated verification or processing failures.

Manage endpoints

Endpoints are workspace-scoped. Use the dashboard at Settings → Webhooks, or:

# Create an endpoint
curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/webhooks" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/hyponema",
    "events": ["post_call_transcription", "dsar.ready"]
  }'

# List
curl "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/webhooks" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY"

# Inspect recent delivery attempts
curl "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/webhooks/$ENDPOINT_ID/deliveries?limit=50" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY"

The URL must be HTTPS and must resolve to a public host (loopback / link-local / private hosts are rejected). The signing secret is returned once on creation — store it in your secret manager.

Event catalog

Event	Fires when
`post_call_transcription`	A conversation has ended and the transcript is persisted.
`escalation.triggered`	A no-go-zone guard escalated a turn.
`dsar.ready`	A DSAR export job has completed and is ready to download.
`fatigue.alert`	The fatigue-detection windowing fired for a user.
`usage.threshold`	A usage threshold (plan limit or alert) was crossed.
`subscription.changed`	A Stripe subscription transitioned status.
`invoice.paid`	A Stripe invoice was paid.
`invoice.failed`	A Stripe invoice payment failed.
`kb.source_ingested`	A knowledge-base source finished ingestion.
`turn.persistence_failed`	A conversation turn failed to persist.
`webhook.disabled`	Hyponema auto-disabled an endpoint after repeated failures.

Subscribe to the event names you need; an empty events list disables delivery without removing the endpoint.

Signature verification

Each request carries an HMAC-SHA256 signature header computed over the raw body. Verify it with the endpoint’s signing secret. Match the timestamp window your platform expects and reject requests outside it.