> ## Documentation Index
> Fetch the complete documentation index at: /docs/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` - Someone new reached the agent for the first time

> [!NOTE]
>
> `subscriber.joined` fires when a new contact is created — currently when someone new writes in by
> email, or when a chat creates a member that did not exist before. The id is kept as-is rather than
> renamed to `contact.created`, because existing automations reference it.

## 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:

```json theme={null}
{
  "event": "subscriber.joined",
  "resource_id": "contact_uuid",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "bot": {
    "id": "agent_uuid",
    "name": "Support 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 'subscriber.joined':
      console.log('New contact:', 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

```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] [Error Handling](/docs/developers/error-handling.md)
>
> Handle webhook errors


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.