Gateway › Integrations

Integrations

Modes

Mode	Receives replies via	Use when
pull	`GET /webhook/<intg>/updates`	You can’t expose a public endpoint.
callback	agent-hub POSTs to your URL	You have a server that receives webhooks.
connector	agent-hub calls the platform’s bot API itself	The platform has a long-polling bot API.

Created on the Integrations page of the web app: id [a-z0-9]{1,16} (default is reserved), pick a mode, optionally set an owner user id. Revoking is permanent; there’s no key rotation — revoke, then create a new one.

Endpoint & auth

POST /webhook/<intg>                                  send an event (pull or callback)
GET  /webhook/<intg>/updates?offset=0&timeout=30&limit=100
POST /webhook                                         the default channel (gateway config)

Authorization: Bearer <api_key>        # or an HMAC signature using the api_key

INTG="mybot"; KEY="<api_key>"; OFFSET=0
while true; do
  RESULT=$(curl -sS "http://127.0.0.1:8788/webhook/$INTG/updates?offset=$OFFSET&timeout=30" \
    -H "Authorization: Bearer $KEY")
  UPDATES=$(echo "$RESULT" | jq -r '.result[]')
  if [ -n "$UPDATES" ]; then
    echo "$UPDATES" | jq .
    OFFSET=$(($(echo "$UPDATES" | jq -r '.update_id' | tail -1) + 1))
  fi
done


offset	Acks by offset: the next GET sends the last `update_id` + 1.
update_id	A queued reply’s `update_id` is its own `message_id`.
retention	Updates are kept for 7 days.
clamps	timeout 0–50 s (default 30), limit 1–100.
id prefix	Inside agent-hub, group and user ids become `<intg>-<id>`; you always send / receive the raw id.

Error	Meaning
`401 integration revoked`	The key has been revoked.
`404 unknown integration`	The id doesn’t exist.
`409 integration is callback mode`	Using pull on a callback-mode channel.
`502 webhook gateway not running`	The webhook gateway isn’t running right now.

Integrations API (web app)

The Integrations page manages channels through the following API:

GET  /api/webhook/integrations                      list configured channels
POST /api/webhook/integrations                       create a new channel
POST /api/webhook/integrations/<intg_id>/revoke       revoke (permanent; 404 on unknown id)
GET  /api/webhook/connector-presets                  list connector presets

POST /api/webhook/integrations accepts id, name, mode (pull | callback | connector) plus mode-specific fields: callback_url for callback mode, preset or config for connector mode, with optional owner_user_id and token.

Status	When
`201`	Created successfully, returns the channel’s info.
`400`	A field required by the mode is missing (e.g. connector mode missing both `preset` and `config`).
`409`	The id already exists.