Quick Start

Get a webhook live that triggers the Bankr agent from Slack, GitHub, Stripe, or any HTTP source — in under 5 minutes.

Prerequisites

• Bankr CLI installed and authenticated (bankr login)

1. Initialize

bankr webhooks init

This creates:

• webhooks/ directory for your handlers
• bankr.webhooks.json config file

2. Add a Webhook

Scaffold a handler with a built-in signature verifier for your upstream provider:

# Slack Event API — generates an HMAC-SHA256 verifier for x-slack-signature
bankr webhooks add daily-summary --provider slack

# GitHub — generates the sha256= HMAC verifier
bankr webhooks add release-bot --provider github

# Stripe — generates the t=<ts>,v1=<sig> verifier
bankr webhooks add charge-listener --provider stripe

# Generic — no signature verifier included, you add your own
bankr webhooks add my-hook

This creates webhooks/<name>/index.ts with a working handler, and adds a safe-default entry to bankr.webhooks.json.

3. Set Environment Variables

Each provider scaffold expects a signing secret as an env var:

bankr webhooks env set SLACK_SIGNING_SECRET=your-signing-secret
bankr webhooks env set GITHUB_WEBHOOK_SECRET=your-webhook-secret
bankr webhooks env set STRIPE_WEBHOOK_SECRET=whsec_...

Env vars are encrypted at rest and injected into your handler as process.env.KEY. See Security for details on how they're stored.

4. Customize the Handler

Open webhooks/<name>/index.ts. The generated scaffold already:

• Reads the raw request body
• Verifies the upstream signature (rejects unverified requests with 401)
• Parses the event
• Returns { prompt, threadId? } for the Bankr agent to execute

You can freely edit the prompt, add your own logic, fetch extra context, etc.

// webhooks/daily-summary/index.ts (Slack provider)
export default async function handler(req: Request): Promise<Response> {
  const rawBody = await req.text();

  if (!verifySlack(req.headers, rawBody, process.env.SLACK_SIGNING_SECRET ?? "")) {
    return new Response("invalid signature", { status: 401 });
  }

  const event = JSON.parse(rawBody);
  if (event.type === "url_verification") {
    return Response.json({ challenge: event.challenge });
  }

  const ev = event.event ?? {};
  const channel = ev.channel ?? "";
  const threadTs = ev.thread_ts ?? ev.ts ?? "";

  return Response.json({
    prompt: `Summarize my portfolio performance in the last 24 hours. Post the reply to Slack channel=${channel} thread_ts=${threadTs}.`,
    threadId: `slack-${channel}-${threadTs}`,
  });
}

That's it for the handler. Bankr wraps the execution layer automatically — no agent SDK, no job polling, no transaction-signing code.

5. Configure Permissions (Optional)

Edit bankr.webhooks.json for this webhook:

{
  "webhooks": {
    "daily-summary": {
      "description": "Slack bot — summarize portfolio on @mention",
      "readOnly": true,
      "allowedRecipients": { "evm": [], "solana": [] },
      "rateLimit": { "perMinute": 10, "perDay": 1000 },
      "maxPayloadBytes": 10240
    }
  }
}

Key fields:

Field	Default	Purpose
readOnly	true	When true, the agent cannot sign/submit transactions.
allowedRecipients	{ evm: [], solana: [] }	Required if you set readOnly: false. Transfers can only go to these.
rateLimit	{ perMinute: 10, perDay: 1000 }	Protects against bursty upstream events.
maxPayloadBytes	10240	Rejects oversize request bodies with a 413.

See Config File for the full reference.

6. Deploy

bankr webhooks deploy

Output:

✔ Deployed 1 webhook(s)

  Webhook:  daily-summary
  URL:      https://webhooks.bankr.bot/u/0xYourWallet/daily-summary
  Version:  1

Your webhook is live. Point your upstream service at that URL.

7. Test It

Direct HTTP test

# Unsigned request — your verifier should reject it
curl -i -X POST https://webhooks.bankr.bot/u/0xYourWallet/daily-summary \
  -H 'Content-Type: application/json' \
  -d '{"hello": "world"}'
# → 401 invalid signature

Provider-side test

• Slack: use "Retry" on the Event Subscriptions page of your app config.
• GitHub: go to the webhook config page and click "Recent Deliveries → Redeliver".
• Stripe: use the Stripe CLI: stripe trigger charge.succeeded.

View logs

bankr webhooks logs daily-summary

Or open the dashboard for a richer view with expandable invocation details.

Next Steps

• Security model — readOnly, allowedRecipients, and how env vars are isolated.
• CLI reference — every bankr webhooks command.
• Examples — drop-in handlers for Slack, GitHub, Stripe, cron, and more.
• Config file — the full bankr.webhooks.json reference.