> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boostgpt.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Create Endpoint">
    Create an endpoint that accepts POST requests
  </Step>

  <Step title="Add Webhook in Dashboard">
    Go to Settings -> Webhooks -> Add Webhook
  </Step>

  <Step title="Enter URL">
    Provide your endpoint URL (must be HTTPS)
  </Step>

  <Step title="Select Events">
    Choose which events to receive
  </Step>
</Steps>

## Webhook Payload

All webhooks send JSON payloads:

```json theme={null}
{
  "event": "crm.contact.created",
  "resource_id": "contact_uuid",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "status": "new",
  "fields": {
    "budget": "$5k"
  },
  "bot": {
    "id": "agent_uuid",
    "name": "Sales Agent"
  }
}
```

## Example Endpoint

### Express.js

```javascript theme={null}
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

```javascript theme={null}
// 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:

```javascript theme={null}
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:

```bash theme={null}
# 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

<Card title="Error Handling" icon="triangle-exclamation" href="/developers/error-handling">
  Handle webhook errors
</Card>