Skip to content

Webhooks

InfonChat supports a generic webhook ingress endpoint that normalizes incoming payloads into the durable runtime inbox.

Endpoints

  • POST /api/v1/webhooks/generic/{workspace_id}

The endpoint:

  1. Validates that the body is a JSON object.
  2. Normalizes headers + payload into a common runtime event envelope.
  3. Writes the normalized event to infonchat.event_inbox.
  4. Returns 202 Accepted with { "accepted": boolean }.

Runtime Ingestion Flow

external webhook
  -> /api/v1/webhooks/generic/{workspace_id}
  -> event_inbox (durable)
  -> runtime inbox worker
  -> event_outbox (durable)
  -> pub/sub runtime topics

Webhook events emit source_kind as webhook.{source} where source defaults to generic.

Generic Endpoint

POST /api/v1/webhooks/generic/{workspace_id} accepts any JSON object and stores the full payload unchanged.

Optional query params:

  • source: sets source_kind as webhook.{source} (for role routing).
  • event_type: explicit event type override.
  • source_identifier: explicit correlation identifier override.
  • dedupe_key: explicit idempotency key override.

Fallback behavior:

  • event_type falls back to payload event, then type, then action, then "received".
  • dedupe_key falls back to x-webhook-id or x-request-id header.
  • source_identifier falls back to explicit value, then dedupe key, payload id, then {source}:{workspace_id}.

Agent Role Routing

The runtime inbox worker supports role-based routing for webhook events.

Webhook events map to role names in the form:

webhook.{source}.{event_type_slug}

Examples:

  • webhook.stripe.payment_succeeded
  • webhook.zendesk.ticket_created
  • webhook.generic.received

If an agent is assigned to a matching role in the workspace, the system can create a chat and enqueue an agent run for that event.

Notes

  • Signature verification is not yet documented as a built-in feature for this endpoint.
  • The endpoint is designed as an ingestion adapter into the durable runtime, not as direct business-logic handlers.