Webhook Verification

Fail-closed HMAC signature verification for inbound bot webhooks

from praisonaiagents import Agent

agent = Agent(name="webhook-agent", instructions="Verify and process incoming webhooks.")
agent.start("Verify the HMAC signature on this incoming webhook from GitHub.")

Inbound webhooks are verified by default — misconfigured secrets return HTTP 401 instead of silently accepting unsigned traffic.

export LINEAR_WEBHOOK_SECRET=your-linear-signing-secret
export LINEAR_OAUTH_TOKEN=your-linear-token
praisonai bot linear --token "$LINEAR_OAUTH_TOKEN"

The user posts a webhook; HMAC verification runs before the agent handles the payload.

Quick Start

1. Set your signing secret

   export LINEAR_WEBHOOK_SECRET=your-linear-secret
   # or for AgentMail:
   export AGENTMAIL_WEBHOOK_SECRET=your-agentmail-secret

2. Run the bot — verification is on by default

   praisonai bot linear --token $LINEAR_OAUTH_TOKEN

3. Local dev without a real platform

   PRAISONAI_INSECURE_WEBHOOKS=true praisonai bot linear --token $LINEAR_OAUTH_TOKEN

Which mode am I in?

How It Works

Configuration Options

Common Patterns

Built-in adapter, secret only — set the platform env var and run the bot; no code required.

Custom adapter with HmacWebhookVerifier:

from praisonai.bots.webhook_security import HmacWebhookVerifier

verifier = HmacWebhookVerifier(
    secret="your-secret",
    signature_headers=["X-Hub-Signature-256"],
    prefix="sha256=",
)

Custom ingress with the shared gate:

from praisonai.bots.webhook_security import enforce_webhook_verification

ok = enforce_webhook_verification(
    accepts_webhooks=True,
    verifier=verifier,
    headers=dict(request.headers),
    raw_body=await request.body(),
    platform="mychat",
)
if not ok:
    return Response(status_code=401)

Best Practices

Related