Skip to content
Bankr Support home
InboxAsk a human

How Do I Trigger My Agent from External Apps (Webhooks)?

Bankr Webhooks allow you to bridge the gap between external applications and your agent. By setting up a webhook, you can trigger your agent to perform tasks whenever an event happens in another app—like receiving a Slack message, a GitHub release, or a successful Stripe payment.

How Webhooks Work

Instead of you manually typing a command, an external service sends an HTTP request to a unique URL. Bankr runs a small piece of code (a "handler") that you've written, which then tells the agent exactly what prompt to execute.

  1. Write a handler: You create a TypeScript file that verifies the incoming request and returns a text prompt for the agent.

  2. Deploy: You push your code to Bankr using the CLI.

  3. Connect: You give the resulting URL to your external service (like Zapier or Slack).

  4. Execute: When the service hits that URL, your agent runs the prompt automatically.

Setting Up Your Webhook

To get started, you'll use the Bankr CLI to deploy your handler code. Once deployed, you will receive a public URL formatted like this: https://webhooks.bankr.bot/u/<wallet>/<name>.

# Deploy your webhook handler
bankr webhooks deploy

You can manage your webhooks, view logs of past executions, and rotate your secrets at bankr.bot/webhooks.

Safety and Permissions

By default, webhooks are designed to be "Safety First." Here are the key protections in place:

  • Read-Only Mode: Every new webhook starts with readOnly: true. This means the agent can check prices or read news, but it cannot move funds or swap tokens unless you explicitly enable write permissions.

  • Transfer Allowlist: Even if you enable write permissions, you can restrict the agent so it can only send tokens to specific, pre-approved addresses.

  • Rate Limiting: You can prevent a "noisy" app from triggering your agent too many times by setting limits (e.g., 10 calls per minute).

  • IP Restrictions: You can restrict access so that only requests from specific IP addresses (like GitHub's or Stripe's servers) are accepted.

Example Use Cases

Webhooks turn your agent into a reactive tool. Here are a few ways to use them:

  • Slack Bot: When someone mentions your agent in Slack, the webhook triggers a prompt like: "Reply to the thread with a summary of my current portfolio holdings."

  • Stripe Payments: When a customer pays you, the webhook can trigger: "Buy $50 worth of ETH using the USDC in my wallet."

  • GitHub Alerts: When a new release is published, the agent can: "Post a summary of this release to our Discord community channel."

Troubleshooting Tips

  • Check the Dashboard: If your webhook isn't firing, visit the Webhooks Dashboard to see the invocation logs and error messages.

  • Verify Signatures: Always ensure your handler code verifies the signature from the calling service (like Slack or Stripe) to make sure the request is legitimate.

  • Environment Variables: Use the dashboard to securely store API keys or signing secrets. These are injected into your handler as process.env.

For a deeper technical dive into writing handlers and managing permissions, visit docs.bankr.bot.