Webhook Integration

Webhooks allow your application to receive real-time notifications about events that occur in your NeuralTalk AI chatbots. This page explains how to set up and use webhooks effectively.

What are Webhooks?

Webhooks are HTTP callbacks that deliver data to your application when specific events happen in NeuralTalk AI. For example, when a user sends a message to your chatbot, we can send an HTTP POST request to a URL you specify with information about the message.

Setting Up Webhooks

1. Create a Webhook Endpoint

First, you need to create an HTTP endpoint on your server that can receive webhook events. This endpoint should:

• Accept POST requests
• Return a 2xx status code quickly to acknowledge receipt
• Process the webhook data asynchronously

2. Register Your Webhook URL

To register a webhook URL:

1. Log in to your NeuralTalk AI Dashboard
2. Navigate to Settings > API > Webhooks
3. Click Add Webhook
4. Enter your endpoint URL
5. Select the events you want to subscribe to
6. Click Save

Webhook Events

NeuralTalk AI supports the following webhook events:

Event	Description
message.created	Triggered when a new message is created in a conversation
conversation.started	Triggered when a new conversation is started
conversation.ended	Triggered when a conversation is ended
knowledge.updated	Triggered when the knowledge base is updated
bot.status.changed	Triggered when a chatbot's status changes

Webhook Payload

Webhook payloads are sent as JSON in the request body. Here's an example payload for a message.created event:

{
  "event": "message.created",
  "timestamp": "2023-06-20T14:22:45Z",
  "data": {
    "message_id": "msg_abc123",
    "conversation_id": "conv_789xyz",
    "text": "What services do you offer?",
    "sender_type": "user",
    "user_id": "user_456",
    "chatbot_id": "bot_123abc",
    "sent_at": "2023-06-20T14:22:45Z"
  }
}

Verifying Webhook Signatures

To ensure the webhook requests are coming from NeuralTalk AI, you should verify the signature included in each request:

1. We include a X-NeuralTalk-Signature header with each webhook request
2. This signature is a HMAC SHA-256 hash of the request body, using your webhook secret as the key
3. You should compute the same hash on your server and compare it with the received signature

Here's an example of how to verify the signature in Node.js:

const crypto = require('crypto');

function verifyWebhookSignature(requestBody, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(requestBody)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(computedSignature, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

// Usage in Express.js
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-neuraltalk-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook event
  console.log('Received webhook:', req.body);
  res.status(200).send('Webhook received');
});

Best Practices

1. Respond quickly: Your endpoint should acknowledge receipt of the webhook with a 2xx HTTP status code as quickly as possible, then process the data asynchronously.

2. Implement retries: NeuralTalk AI will retry failed webhook deliveries using an exponential backoff strategy for up to 24 hours.

3. Verify signatures: Always verify the signature to ensure the webhook came from NeuralTalk AI.

4. Handle duplicates: Occasionally, you might receive the same webhook more than once. Use the event ID to deduplicate events.

5. Monitor failures: Set up monitoring for webhook failures to quickly identify and fix integration issues.

Testing Webhooks

You can test your webhook implementation using our webhook testing tool:

1. Navigate to Settings > API > Webhooks
2. Select the webhook you want to test
3. Click Test Webhook
4. Choose an event type and click Send Test Event

This will send a test event to your endpoint so you can verify it's working correctly.

---

For additional information or questions about webhooks, please contact our support team.