Webhook API Guide

This page helps you setting up your chatbot webhooks.

The Webhook API guide allows you to set-up webhooks to receive a POST request on when an event or more is triggered.

Payload

Key	Type	Description
eventType	string	event type (eg. lead.submit)
chatbotId	string	Chatbot ID
payload	Object	Payload of the event. Learn more

Event types

These are the list of events supported in webhooks.

lead.submit - When a customer submit his info (Name, Email, and Phone) to your chatbot.


{
  conversationId: string,
  customerEmail: string,
  customerName: string,
  customerPhone: string
}

Receiving the webhook request

You can receive the payload by accessing the body same as any request. But it is recommended to to check the request header x-chatzuri-signature for securing your endpoint from spam from anyone knows your endpoint.

You can achieve this by using SHA-1 (Secure Hash Algorithm 1) function to generate a signature for the request and compare it with x-chatzuri-signature found in the request headers. If the are identical then the request is from Chatzuri.

Example Request


import crypto from 'crypto'
import { Request, Response } from 'express'

// Note: In this example json body parser is enabled in the app

export async function webhookHandler(req: Request, res: Response) {
  if (req.method === 'POST') {
    const { SECRET_KEY } = process.env

    if (typeof SECRET_KEY != 'string') {
      throw new Error('No secret key found');
    }
    
    const receivedJson = req.body

    const rawBody = Buffer.from(JSON.stringify(receivedJson))

    const bodySignature = sha1(rawBody, secretKey)

    if (requestBodySignature !== req.headers['x-chatzuri-signature']) {
      return res.status(400).json({ message: "Signature didn't match" })
    }

    console.log('Received:', receivedJson)
    
    /*
    Body example for leads.submit event
    {
      eventType: 'leads.submit',
      chatbotId: 'xxxxxxxx',
      payload: {
        conversationId: 'xxxxxxxx',
        customerEmail: '[email protected]',
        customerName: 'Example',
        customerPhone: '123'
      }
    }
    */
		

    res.status(200).end('OK')
  } else {
    res.setHeader('Allow', 'POST')
    res.status(405).end('Method Not Allowed')
  }
}

function sha1(data: Buffer, secret: string): string {
  return crypto.createHmac('sha1', secret).update(data).digest('hex')
}

Respond to the event webhook

Return a JSON object with the following structure to indicate your endpoint has received the event webhook


{
  "status": "accepted"
}

Home: API Documentation