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": "user@example.com",
    "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

Your webhook endpoint should respond with a 2xx status code to acknowledge receipt
Implement retry logic in case your endpoint is temporarily unavailable
Process webhooks asynchronously to ensure quick response times
Verify the webhook source using request headers
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

Sub-processors Getting Started