Webhooks

Receive real-time events from BoostGPT

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
• crm.contact.created - CRM contact created
• crm.contact.updated - CRM contact updated
• crm.contact.deleted - CRM contact deleted or archived
• crm.note.created - CRM note created
• crm.deal.created - CRM deal created
• crm.deal.updated - CRM deal updated
• crm.deal.deleted - CRM deal deleted
• crm.deal.stage_changed - CRM deal moved between stages
• crm.pipeline.created - CRM pipeline created
• crm.pipeline.updated - CRM pipeline updated
• crm.pipeline.stage.created - CRM pipeline stage created
• crm.pipeline.stage.updated - CRM pipeline stage updated
• crm.pipeline.stage.deleted - CRM pipeline stage deleted
• crm.field.created - CRM custom field created
• crm.field.updated - CRM custom field updated
• crm.field.deleted - CRM custom field deleted
• crm.task.created - CRM task created
• crm.task.updated - CRM task updated
• crm.task.deleted - CRM task deleted
• crm.task.reminder.sent - CRM task reminder sent

Setup Webhook

1. Create Endpoint

   Create an endpoint that accepts POST requests

2. Add Webhook in Dashboard

   Go to Settings -> Webhooks -> Add Webhook

3. Enter URL

   Provide your endpoint URL (must be HTTPS)

4. Select Events

   Choose which events to receive

Webhook Payload

All webhooks send JSON payloads:

{
  "event": "crm.contact.created",
  "resource_id": "contact_uuid",
  "name": "Jane Doe",
  "email": "[e-mail]",
  "status": "new",
  "fields": {
    "budget": "$5k"
  },
  "bot": {
    "id": "agent_uuid",
    "name": "Sales 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 'crm.contact.created':
      console.log('New contact:', req.body.email);
      break;
    case 'crm.task.reminder.sent':
      console.log('Reminder sent:', req.body.title);
      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