AiHummer
English▾
Log in
v1.0.x▾
v1.0.xstable
{ }Swagger
API/Inbound & Integration Triggers

Inbound & Integration Triggers

v1.0.x · updated 2026-07-05

Beyond the OpenAI-compatible API, AiHummer accepts inbound messages from connectors, automation platforms and a browser widget, and emits a server-side event stream you can subscribe to. These endpoints are how external systems deliver work to the gateway and how UIs stay live.

Inbound endpoints

Inbound endpoints are how channel connectors and custom integrations hand a message to the turn engine. They are secured by an HMAC shared secret sent in the X-AIHummer-Inbound-Secret header (the AIHUMMER_INBOUND_SECRET settings-catalog key — configured in the admin UI under Management → Settings or with aihummer settings set, not in gateway.env).

Method & path Purpose
POST /v1/inbound/telegram Native Telegram inbound payloads
POST /v1/inbound/generic Generic inbound for email→webhook, cron and custom apps
POST /v1/inbound/binding/status Report channel-binding status

The generic endpoint is the simplest way to feed any source into AiHummer. Send a small JSON body with the channel name, a stable external identifier and the message text:

curl https://your-aihummer.example/v1/inbound/generic \
  -H "X-AIHummer-Inbound-Secret: $AIHUMMER_INBOUND_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "external_id": "ticket-4821",
    "text": "A customer asks whether order #4821 has shipped."
  }'

[!NOTE] The generic inbound dispatcher needs a default workspace. Set AIHUMMER_DEFAULT_WORKSPACE_ID so inbound messages can be routed.

[!WARNING] Inbound endpoints are not protected by an ah- API key — they rely on the X-AIHummer-Inbound-Secret HMAC. Keep that secret out of client-side code and rotate it if it leaks.

Integration triggers (Zapier / Make)

POST /v1/integrations/trigger is the entry point for low-code automation platforms such as Zapier and Make. The endpoint is disabled by default: until the AIHUMMER_INBOUND_TRIGGER_SECRET setting is configured it responds with 501 Not Implemented. This is a separate secret, distinct from AIHUMMER_INBOUND_SECRET; like every settings-catalog key it is set in the admin UI (Management → Settings) or with aihummer settings set.

Once configured, the endpoint accepts either an X-AIHummer-Signature HMAC or a Bearer token of the form Authorization: Bearer <the AIHUMMER_INBOUND_TRIGGER_SECRET value>.

curl https://your-aihummer.example/v1/integrations/trigger \
  -H "Authorization: Bearer $AIHUMMER_INBOUND_TRIGGER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "zapier",
    "external_id": "lead-99",
    "text": "New lead captured from the contact form."
  }'

Web widget

The embeddable web widget uses two endpoints: one to open a session and one to stream the assistant’s reply.

Method & path Purpose
POST /v1/web/session Open a widget session
GET /v1/web/stream Receive widget responses as SSE 
# 1) Open a session
curl https://your-aihummer.example/v1/web/session \
  -H "Content-Type: application/json" \
  -d '{}'

# 2) Stream responses (Server-Sent Events)
curl -N https://your-aihummer.example/v1/web/stream

Event stream

GET /v1/events/stream is a resumable Server-Sent Events feed of gateway events. The endpoint has two hard requirements:

  1. The ?workspace_id=<id> parameter is mandatory — without it the request is rejected with 400. A tenant guard verifies that the workspace belongs to the caller’s tenant; someone else’s workspace_id yields 403.
  2. Authentication is required — an admin session (cookie) or an ah- API key in an Authorization: Bearer header. Without it the response is 401.

Pass a ?since= cursor to resume from where a previous connection left off, so a reconnect never loses events.

# Subscribe from the beginning
curl -N -H "Authorization: Bearer ah-..." \
  "https://your-aihummer.example/v1/events/stream?workspace_id=<id>"

# Resume after a known cursor
curl -N -H "Authorization: Bearer ah-..." \
  "https://your-aihummer.example/v1/events/stream?workspace_id=<id>&since=<cursor>"

[!TIP] Treat the value carried by each event as the next since cursor. On reconnect, replay from that cursor to guarantee at-least-once delivery to your consumer.

Where to next