AiHummer docs
v1.0.x ▾
v1.0.x stable
RU EN
API /Inbound & Integration Triggers

Inbound & Integration Triggers

v1.0.x · updated 2026-06-26

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 (configured via AIHUMMER_INBOUND_SECRET).

Method & pathPurpose
POST /v1/inbound/telegramNative Telegram inbound payloads
POST /v1/inbound/genericGeneric inbound for email→webhook, cron and custom apps
POST /v1/inbound/binding/statusReport 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. It accepts either an X-AIHummer-Signature HMAC or a Bearer token.

curl https://your-aihummer.example/v1/integrations/trigger \
  -H "X-AIHummer-Signature: $SIGNATURE" \
  -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 & pathPurpose
POST /v1/web/sessionOpen a widget session
GET /v1/web/streamReceive 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. 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 https://your-aihummer.example/v1/events/stream

# Resume after a known cursor
curl -N "https://your-aihummer.example/v1/events/stream?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