Webhooks

Overview

Webhooks allow you to receive real-time notifications when events occur in your BoostGPT project.

Available Events

connector.created - MCP connector/server created
connector.updated - MCP connector/server updated
connector.cloned - MCP connector/server cloned
connector.deleted - MCP connector/server deleted
memory.created - Memory source created
memory.updated - Memory source updated
memory.deleted - Memory source deleted
subscriber.joined - Subscriber joined an agent
subscriber.verified - Subscriber verified their account
subscriber.deactivated - Subscriber deactivated their agent account
subscriber.subscription.checkout_started - Subscriber started checkout
subscriber.subscription.created - Subscriber subscription created
subscriber.subscription.renewed - Subscriber subscription renewed
subscriber.subscription.cancel_requested - Subscriber requested cancellation
subscriber.subscription.cancelled - Subscriber subscription cancelled
subscriber.subscription.paused - Subscriber subscription paused
subscriber.subscription.resumed - Subscriber subscription resumed
subscriber.subscription.refunded - Subscriber payment refunded

Setup Webhook

Create Endpoint

Create an endpoint that accepts POST requests

Add Webhook in Dashboard

Go to Settings -> Webhooks -> Add Webhook

Enter URL

Provide your endpoint URL (must be HTTPS)

Select Events

Choose which events to receive

Webhook Payload

All webhooks send JSON payloads:

{
  "event": "subscriber.joined",
  "resource_id": "subscriber_uuid",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "bot": {
    "id": "agent_uuid",
    "name": "Support Agent"
  }
}

Example Endpoint

Express.js

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/boostgpt', (req, res) => {
  const { event, data } = req.body;

  console.log('Received event:', event);

  switch (event) {
    case 'subscriber.joined':
      console.log('New subscriber:', req.body.email);
      break;
    case 'subscriber.subscription.created':
      console.log('New customer:', req.body.email);
      break;
    default:
      console.log('Unknown event:', event);
  }

  // Acknowledge receipt
  res.status(200).json({ received: true });
});

app.listen(3000);

Next.js API Route

// pages/api/webhooks/boostgpt.js

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  const { event } = req.body;

  // Handle event
  if (event === 'subscriber.joined') {
    // Add to email list
    await addToMailchimp(req.body.member?.user?.email);
  }

  return res.status(200).json({ received: true });
}

Verify Webhook Signature

Verify webhooks are from BoostGPT:

import crypto from 'crypto';

function verifySignature(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return hash === signature;
}

app.post('/webhooks/boostgpt', (req, res) => {
  const signature = req.headers['x-boostgpt-signature'];
  const secret = process.env.WEBHOOK_SECRET;

  if (!verifySignature(req.body, signature, secret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook
  res.status(200).json({ received: true });
});

Best Practices

Return 200 quickly - Don’t process long tasks in webhook handler
Use queues - Add events to a queue for async processing
Verify signatures - Always verify webhook authenticity
Handle retries - Respond with 200 to prevent retries
Log events - Keep logs for debugging

Testing Webhooks

Test locally using ngrok:

# Start your local server
node server.js

# In another terminal, expose it
ngrok http 3000

# Use the ngrok URL in dashboard
https://abc123.ngrok.io/webhooks/boostgpt

Next Steps

Error Handling

Handle webhook errors

Getting Started

Choose Your Path

Providers & Models

Overview

Available Events

Setup Webhook

Webhook Payload

Example Endpoint

Express.js

Next.js API Route

Verify Webhook Signature

Best Practices

Testing Webhooks

Next Steps

Error Handling

​Overview

​Available Events

​Setup Webhook

​Webhook Payload

​Example Endpoint

​Express.js

​Next.js API Route

​Verify Webhook Signature

​Best Practices

​Testing Webhooks

​Next Steps

Error Handling

Overview

Available Events

Setup Webhook

Webhook Payload

Example Endpoint

Express.js

Next.js API Route

Verify Webhook Signature

Best Practices

Testing Webhooks

Next Steps