Documentation

Webhook

# Webhook Documentation

Webhooks allow you to receive real-time HTTP notifications when certain events occur in your chatbot system. This can be useful for integrating with other systems, tracking usage, or implementing custom business logic.

## Use Cases

- Track chat usage per user
- Implement usage limits (e.g., 50 chats per month for free users)
- Log chat history in your own system
- Trigger custom workflows based on user interactions

## Events

Currently, we support the following event:

- `chat` - Triggered when a user sends a message to the chatbot

## Webhook Payload Format

When an event occurs, we'll send a POST request to your configured webhook URL with a JSON payload.

### Request Format

```
{
 "event": "chat",
 "payload": {
 "email": "[email protected]",
 "chatbotId": "bot_123456",
 "question": "What is the weather today?",
 "name": "John Doe"
 }
}
```

### Headers

```
Content-Type: application/json
User-Agent: AskYourDatabase-Webhook
```

### Field Descriptions

| Field | Type | Description |
| --- | --- | --- |
| event | string | The type of event that occurred (currently only "chat") |
| payload.email | string | The email address of the user who initiated the chat |
| payload.chatbotId | string | The unique identifier of the chatbot |
| payload.question | string | The message sent by the user |
| payload.name | string | The name of the user (if provided) |

## Best Practices

1. Your webhook endpoint should respond with a 2xx status code to acknowledge receipt
2. Implement retry logic in case your endpoint is temporarily unavailable
3. Process webhooks asynchronously to ensure quick response times
4. Verify the webhook source using request headers
5. Handle duplicate events gracefully (implement idempotency)

## Example Implementation

Here's a simple example of how to handle the webhook in Node.js:

```
app.post('/webhook', async (req, res) => {
 const { event, payload } = req.body;
 
 if (event === 'chat') {
 const { email, chatbotId, question, name } = payload;
 
 // Process the chat event
 await updateUserChatCount(email);
 
 // Acknowledge receipt
 res.status(200).json({ received: true });
 }
});
```

## Rate Limits and Retry Policy

- We will attempt to deliver webhooks for up to 24 hours
- Failed deliveries will be retried with exponential backoff
- Maximum of 5 retry attempts per event

[Sample Databases](https://www.askyourdatabase.com/docs/sample-db)[Security Portal](https://www.askyourdatabase.com/docs/security)