Webhooks

Webhooks allow your application to receive real-time notifications when events occur in BotPhi — such as new messages, bot status changes, or errors.

Setting Up Webhooks

POST /v1/webhooks

{
  "url": "https://your-app.com/api/botphi-webhook",
  "events": ["message.received", "message.sent", "bot.status_changed"],
  "secret": "whsec_your-signing-secret"
}

Event Types

• message.received — A user sent a message to the bot
• message.sent — The bot responded to a user
• bot.status_changed — Bot status changed (running, paused, failed)
• bot.deployed — A new deployment completed successfully
• bot.error — The bot encountered a runtime error

Verifying Signatures

Every webhook request includes an X-BotPhi-Signature header. Verify it to ensure the request is from BotPhi:

import crypto from "node:crypto";

function verifyWebhook(payload: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}