Gateway Inbound Hooks

The gateway now ships in the praisonai-bot package. praisonai serve gateway still works exactly as documented here; for a standalone install see praisonai-bot Migration.

Inbound hooks expose a POST /hooks/<path> endpoint on the gateway — point any external service (GitHub Actions, Linear, Gmail push, Sentry alerts) at it and the gateway runs an agent and delivers the reply to a configured channel.

from praisonaiagents import Agent
from praisonai.gateway import Gateway

agent = Agent(name="triage", instructions="Triage inbound alerts and summarise the action needed.")
gw = Gateway(agents=[agent])
gw.register_hook({"path": "alerts", "agent": "triage", "auth": "my-shared-secret"})
gw.start()

The user POSTs JSON to /hooks/<path>; the gateway authenticates the payload, runs the mapped agent, and delivers the reply to the configured channel.

Quick Start

Define a hook and start the gateway

from praisonai.gateway import Gateway
from praisonaiagents import Agent

agent = Agent(
    name="triage",
    instructions="Triage the inbound alert and summarise the action needed."
)

gw = Gateway(agents=[agent])
gw.register_hook({
    "path": "alerts",
    "agent": "triage",
    "auth": "my-shared-secret",
    "deliver_to": "telegram:123456789",
    "message": "Alert from {{ payload.source }}: {{ payload.title }}",
})
gw.start()

Point your external service at the hook URL

curl -X POST https://your-gateway/hooks/alerts \
  -H "Authorization: Bearer my-shared-secret" \
  -H "Content-Type: application/json" \
  -d '{"source": "Sentry", "title": "NullPointerException in prod"}'

The agent replies to Telegram automatically

No polling, no webhook handler code — the gateway does it all.

How It Works

Three Ways to Register a Hook

Python
YAML (gateway.yaml)
CLI

from praisonai.gateway import Gateway
from praisonaiagents import Agent

agent = Agent(
    name="email-triager",
    instructions="Triage the email and decide on an action."
)

gw = Gateway(agents=[agent])

gw.register_hook({
    "path": "gmail",
    "agent": "email-triager",
    "action": "agent",
    "auth": "shared-secret",
    "session_key": "hook:gmail:{from}",
    "idempotency_key": "{message_id}",
    "deliver_to": "telegram:123456789",
    "message": "New mail from {{ payload.from }}: {{ payload.subject }}",
})

gw.start()

hooks:
  - path: gmail
    agent: email-triager
    action: agent
    auth: shared-secret
    session_key: "hook:gmail:{from}"
    idempotency_key: "{message_id}"
    deliver_to: telegram:123456789
    message: "New mail from {{ payload.from }}: {{ payload.subject }}"

Start the gateway pointing at the config:

praisonai gateway start --config gateway.yaml

# Path is a positional argument, not --path
praisonai gateway hooks add gmail \
  --agent email-triager \
  --deliver-to telegram:123456789 \
  --message "New mail from {from}: {subject}"

praisonai gateway hooks list

praisonai gateway hooks remove gmail

Flag	Type	Default	Description
`<path>` (positional)	`str`	required	Hook path — `gmail` exposes `POST /hooks/gmail`
`--agent`	`str`	first registered agent	Agent id to run
`--action`	`str`	`agent`	`agent` runs a turn; `wake` nudges a session
`--auth`	`str`	none	Bearer token / shared secret for this hook
`--session-key`	`str`	none	Session key template (see HookConfig Options)
`--idempotency-key`	`str`	none	Idempotency key template
`--deliver-to`	`str`	none	`platform:target` delivery spec, e.g. `telegram:12345`
`--message`	`str`	none	Message template built from the payload
`--config`	`str`	`gateway.yaml`	Path to the gateway configuration file

Only these nine options are exposed through the CLI. The full HookConfig (HMAC signing, event allow-lists, metadata, etc.) is available via YAML / SDK only — see the HookConfig Options table below.

HookConfig Options

Option	Type	Default	Description
`path`	`str`	required	URL segment after `/hooks/`. `"gmail"` exposes `POST /hooks/gmail`. Must be non-empty.
`agent`	`str`	`None`	Agent name/id to run. Falls back to the gateway’s first registered agent.
`action`	`str`	`"agent"`	`"agent"` runs a new turn; `"wake"` nudges an existing session without a new message.
`auth`	`str`	`None`	Bearer token required on inbound requests. Falls back to the gateway’s global `auth_token`.
`session_key`	`str`	`None`	Template for the session id, e.g. `"hook:gmail:{message_id}"`. Defaults to `"hook:{path}"`.
`idempotency_key`	`str`	`None`	Template for the dedup key. When unset, hashes the entire payload.
`deliver_to`	`str`	`None`	`platform:target` delivery spec, e.g. `"telegram:123456789"`. Omit to skip outbound delivery.
`message`	`str`	`None`	Template for the message built from the payload and sent to the agent.
`enabled`	`bool`	`True`	Whether the hook is active. `false` returns 404.
`metadata`	`dict`	`{}`	Free-form key/value pairs passed to the agent context.
`secret`	`str`	`None`	HMAC signing secret. When set, the gateway verifies the provider signature over the raw body before any agent runs and rejects (401) a missing/invalid signature — fail-closed.
`signature_header`	`str`	`None`	Header carrying the signature. Auto-defaults to `"X-Hub-Signature-256"` when `secret` is set with no explicit header.
`signature_algo`	`str`	`"sha256"`	Digest for the HMAC. Any name `hashlib.new` accepts (e.g. `"sha1"`, `"sha512"`).
`signature_prefix`	`str`	`None`	Optional signature prefix, e.g. `"sha256="`.
`events`	`list[str]`	`None`	Allow-list of event types. Unmatched deliveries are ack’d (200) with no LLM turn. A string is coerced to a single-element list.
`event_header`	`str`	`None`	Header carrying the event type, e.g. `"X-GitHub-Event"`. When omitted the event is read from the payload as a dotted path (defaulting to `"event"`).
`deliver_only`	`bool`	`False`	When `True` the rendered `message` is the delivered content, routed straight through `deliver_to` with no LLM turn.

`hooks.idempotency` (gateway-level, not per-hook)

Option	Type	Default	Description
`store_backend`	`str`	`"memory"`	`"memory"` (per-process, zero-dep) or `"sqlite"` (durable, survives restart). Unknown values fall back to `"memory"` with a debug log.

Also accepted as siblings when hooks: is a list:

hooks_idempotency: { store_backend: sqlite }
idempotency: { store_backend: sqlite }
Under gateway: → gateway.hooks_idempotency: { store_backend: sqlite }

Templating

Both {{ payload.x }} (Jinja-style) and {x} (format-string style) are accepted:

message: "New mail from {{ payload.from }}: {{ payload.subject }}"
session_key: "hook:gmail:{message_id}"

Rules:

The leading payload. is optional — {{ payload.from }} and {from} resolve identically.
Missing keys render as empty strings — the template never raises on partial payloads.
Single-pass substitution — a payload value containing {...} is never re-expanded (injection-safe).
Interpolated payload values are automatically fenced as untrusted request data on agent-turn hooks. Operator template text stays outside the fence. See Untrusted Request Fencing.

Actions

"agent" (default) — runs a full agent turn with the rendered message as the user input:

action: agent
message: "Triage: {{ payload.title }}"

"wake" — nudges an existing session (triggers proactive delivery or a scheduled check-in) without injecting a new user message:

action: wake
session_key: "daily:{{ payload.user_id }}"

Idempotency & Retries

The gateway deduplicates concurrent and retried deliveries:

When idempotency_key is set, the key is rendered from the payload and hashed as SHA-256(path + "\x00" + rendered_key).
When unset, the entire payload is JSON-canonicalized and hashed.
The key is reserved in-flight atomically — concurrent identical POSTs dedup across the await boundary.
The key is committed only after a successful agent run — transient failures remain retryable.

External services that retry on timeout (e.g. GitHub webhooks, Linear) are safe to point directly at inbound hooks without additional dedup logic on your side.

Dedup Store — Memory vs Durable (SQLite)

By default the dedup store is in-memory (per process). A webhook provider that retries after a gateway restart within its retry window — or a deployment with replicas > 1 — needs the dedup key to survive that, otherwise the retry starts a duplicate agent run (duplicate reply, duplicate tool action). Opt in to the durable SQLite backend:

hooks:
  idempotency:
    store_backend: sqlite      # "memory" (default) | "sqlite"
  hooks:
    - path: gmail
      agent: assistant
      # ...

When hooks: is a top-level list (the common shape), use the sibling key instead:

hooks_idempotency:
  store_backend: sqlite

hooks:
  - path: gmail
    agent: assistant
    # ...

Backend	Survives restart?	Shared across replicas?	Dependencies	When to use
`memory` (default)	❌	❌	none	Single-replica dev / low-stakes deployments
`sqlite`	✅	✅ (when the DB file is shared)	stdlib `sqlite3` only	Production, any provider with retries, multi-replica

Storage details (SQLite):

DB file: ~/.praisonai/state/hook_idempotency.sqlite (auto-created; same state dir as the ingress journal and outbound queue).
WAL mode with synchronous=NORMAL for durable but low-latency writes.
reserve is a crash-safe UNIQUE insert — a redelivery and a concurrent duplicate both fail on the primary-key constraint (this is the inbound analogue of the outbound queue’s UNIQUE idempotency_key).
Bounded: max 10,000 recorded entries + 24h TTL, pruned lazily on reserve.
Crash recovery: a durable inflight reservation whose run neither recorded nor released it (only cause: a process crash during the hook) is reclaimable after a 15 min inflight_lease_seconds lease, so the provider’s post-restart retry re-runs instead of being deduplicated for the full TTL. recorded keys are never touched by the lease.
On any failure to build the SQLite store, the gateway falls back to the in-memory default so inbound delivery keeps working (a warning is logged).

For a custom store, implement IdempotencyStoreProtocol and inject it — the memory and SQLite backends are the two built-ins.

Hot-reload: flipping store_backend via reload_config rebuilds the store lazily on the next reserve. See Gateway Hot-Reload.

Security

Authorization: Bearer <token> is the only accepted form. The ?token= query-parameter path was removed because it leaks the shared secret into access logs.

Behaviour	Detail
Auth required	401 on missing or invalid `Authorization: Bearer` header
Per-hook auth	`auth` field on the hook overrides the gateway’s global `auth_token`
Malformed JSON	400 response, no agent run
Missing agent	500 when the hook names an agent that isn’t registered (no silent fallback to another agent)
Disabled hook	404 when `enabled: false`
Untrusted-payload fencing	On for agent-turn hooks; interpolated `{{ payload.x }}` values wrapped in `<external_request_payload>`. Off for `deliver_only: true` where the message is delivered verbatim.

Verifying Provider Signatures (HMAC)

Set secret to have the gateway verify the provider’s HMAC signature over the raw request body — a missing or invalid signature is rejected with 401 before any agent runs. Verification is fail-closed and opt-in: with no secret set, nothing changes. When secret is set without an explicit signature_header, the header defaults to X-Hub-Signature-256 (the GitHub/webhook convention) so a bare secret is a working config, not a 401 trap.

GitHub (Python)
GitHub (YAML)
Stripe (YAML)

from praisonaiagents import Agent
from praisonai.gateway import Gateway

triager = Agent(
    name="triager",
    instructions="Triage this GitHub issue and post a one-line action."
)

gw = Gateway(agents=[triager])
gw.register_hook({
    "path": "github",
    "agent": "triager",
    "secret": "${GITHUB_WEBHOOK_SECRET}",
    "signature_prefix": "sha256=",          # X-Hub-Signature-256 is auto-defaulted
    "deliver_to": "slack:#triage",
    "message": "New {{ payload.action }} on #{{ payload.issue.number }}: {{ payload.issue.title }}",
})
gw.start()

hooks:
  - path: github
    agent: triager
    secret: "${GITHUB_WEBHOOK_SECRET}"
    signature_prefix: "sha256="            # signature_header defaults to X-Hub-Signature-256
    deliver_to: "slack:#triage"
    message: "New {{ payload.action }} on #{{ payload.issue.number }}: {{ payload.issue.title }}"

hooks:
  - path: stripe
    agent: billing-support
    secret: "${STRIPE_WEBHOOK_SECRET}"
    signature_header: "Stripe-Signature"
    signature_algo: "sha256"
    deliver_to: "slack:#billing"
    message: "Stripe event {{ payload.type }} for {{ payload.data.object.customer }}"

Test locally by signing the exact body you POST:

SECRET="my-signing-secret"
BODY='{"action":"opened","issue":{"number":42,"title":"Bug"}}'
SIG="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')"

curl -X POST http://localhost:8765/hooks/github \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: $SIG" \
  -H "X-GitHub-Event: issues" \
  -d "$BODY"

The signature is computed over the raw bytes the provider signed. Do not re-serialize the payload before signing — sign the exact body you send.

Event Filtering

Set events to an allow-list so only matching deliveries run a turn — everything else is a cheap 200 {"ok": true, "skipped": "event"} with no LLM cost. The event type is read from event_header (a request header) or, when that header is absent, from the payload as a dotted path (defaulting to "event").

hooks:
  - path: github
    agent: triager
    event_header: "X-GitHub-Event"
    events: ["issues.opened", "pull_request.opened"]
    deliver_to: "slack:#triage"
    message: "New {{ payload.action }} on #{{ payload.issue.number }}"

GitHub sends the base event (issues) in the header and the sub-type in the payload’s action. A namespaced filter like issues.opened matches only when action == "opened" — fail-closed: a delivery that omits action is never admitted, so a bare issues event cannot slip through a filter that only allows issues.opened. Read the event from a payload field instead of a header by pointing event_header at a dotted path:

hooks:
  - path: stripe
    deliver_only: true
    deliver_to: "slack:#billing"
    event_header: "type"                    # read payload["type"]
    events: ["invoice.payment_failed"]
    message: "⚠️ Payment failed for {{ payload.data.object.customer }}"

Deliver-Only Mode (no LLM turn)

Set deliver_only: true to route the rendered message straight to deliver_to — no agent, no LLM cost, sub-second forwarding.

Because deliver_only bypasses the agent, no untrusted-request fence is added — the recipient never sees literal <external_request_payload> markup.

hooks:
  - path: sentry
    deliver_only: true
    deliver_to: "telegram:${OPS_CHAT_ID}"
    secret: "${SENTRY_WEBHOOK_SECRET}"
    signature_header: "Sentry-Signature"
    message: "🚨 {{ payload.project }}: {{ payload.event.title }}\n{{ payload.url }}"

gw.register_hook({
    "path": "sentry",
    "deliver_only": True,                   # zero LLM cost, sub-second forwarding
    "deliver_to": "telegram:${OPS_CHAT_ID}",
    "secret": "${SENTRY_WEBHOOK_SECRET}",
    "signature_header": "Sentry-Signature",
    "signature_algo": "sha256",
    "message": "🚨 {{ payload.project }}: {{ payload.event.title }}\n{{ payload.url }}",
})

deliver_only composes with signature verification and event filtering and requires deliver_to. Response shapes:

Outcome	Response
Delivered	`{"ok": true, "action": "deliver", "delivered": true}`
Empty rendered message	`{"ok": true, "action": "deliver", "delivered": false, "skipped": "empty message"}`
Missing `deliver_to`	`{"ok": false, "error": "deliver_only hook requires 'deliver_to'"}`
Delivery failed	`{"ok": false, "error": "hook delivery failed", "delivered": false}`

Use deliver_only for notification forwarding — Sentry → Telegram, CI → Slack — where the payload already contains the exact text to send. No agent turn means zero LLM cost and near-instant delivery.

End-to-End Example: Gmail → Triage Agent → Telegram

hooks:
  - path: gmail
    agent: email-triager
    action: agent
    auth: ${GMAIL_HOOK_SECRET}
    session_key: "gmail:{message_id}"
    idempotency_key: "{message_id}"
    deliver_to: telegram:123456789
    message: |
      From: {{ payload.from }}
      Subject: {{ payload.subject }}
      Snippet: {{ payload.snippet }}
      
      Triage this email and suggest a one-line action.

Gmail push subscription fires POST /hooks/gmail with the email payload.
Gateway verifies the bearer token from $GMAIL_HOOK_SECRET.
Session key gmail:<message_id> scopes the conversation to this email thread.
The rendered message is sent to the email-triager agent.
The agent’s reply is delivered to Telegram chat 123456789.

Best Practices

Always set an idempotency_key for event-driven sources

External webhooks retry on timeout. Without an idempotency_key, a slow agent run followed by a timeout retry will run the agent twice. Use a message or event id from the payload.

Use per-hook auth tokens, not the global token

Set a distinct auth secret per hook so you can rotate individual secrets without restarting the gateway or changing the global token.

Set session_key to scope conversations

Without session_key, all deliveries to a hook share the same session (hook:<path>). Use a payload field like {user_id} or {message_id} to isolate conversations by sender or thread.

Test locally with curl before connecting a real service

curl -X POST http://localhost:8765/hooks/gmail \
  -H "Authorization: Bearer my-shared-secret" \
  -H "Content-Type: application/json" \
  -d '{"from": "alice@example.com", "subject": "Hello", "message_id": "test-001"}'

Webhook Verification

HMAC signature verification for outbound bot webhooks (different surface)

Proactive Delivery

Delivery routing — the channel:target format used in deliver_to

Gateway Overview

Gateway configuration, channels, and multi-bot mode

Gateway CLI

All gateway CLI commands including hooks add / list / remove

Untrusted Request Fencing

How inbound payloads are fenced as data before the agent sees them

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Gateway Inbound Hooks

Quick Start

How It Works

Three Ways to Register a Hook

HookConfig Options

`hooks.idempotency` (gateway-level, not per-hook)

Templating

Actions

Idempotency & Retries

Dedup Store — Memory vs Durable (SQLite)

Security

Verifying Provider Signatures (HMAC)

Event Filtering

Deliver-Only Mode (no LLM turn)

End-to-End Example: Gmail → Triage Agent → Telegram

Best Practices

Webhook Verification

Proactive Delivery

Gateway Overview

Gateway CLI

Untrusted Request Fencing

​Quick Start

​How It Works

​Three Ways to Register a Hook

​HookConfig Options

​hooks.idempotency (gateway-level, not per-hook)

​Templating

​Actions

​Idempotency & Retries

​Dedup Store — Memory vs Durable (SQLite)

​Security

​Verifying Provider Signatures (HMAC)

​Event Filtering

​Deliver-Only Mode (no LLM turn)

​End-to-End Example: Gmail → Triage Agent → Telegram

​Best Practices

​Related

Webhook Verification

Proactive Delivery

Gateway Overview

Gateway CLI

Untrusted Request Fencing

Quick Start

How It Works

Three Ways to Register a Hook

HookConfig Options

`hooks.idempotency` (gateway-level, not per-hook)

Templating

Actions

Idempotency & Retries

Dedup Store — Memory vs Durable (SQLite)

Security

Verifying Provider Signatures (HMAC)

Event Filtering

Deliver-Only Mode (no LLM turn)

End-to-End Example: Gmail → Triage Agent → Telegram

Best Practices

Related