Webhook API Guide

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

Create a webhook

Webhooks are configured on the action that produces the event. For lead submissions, use the Collect Leads action:

Go to Build > Actions and open your Collect Leads action.
Click the Webhooks tab in the action settings.
Enter the URL that should receive the POST request, then click Create Webhook.

Other actions that emit events, such as custom forms, have the same Webhooks tab. For phone call summaries, the webhook is configured on the phone channel instead:

Go to Phone > Connections on an AI agent with a phone number assigned.
In the Call summary webhook card, enter the URL that should receive the POST request, then click Create webhook.

The same event can also be subscribed from Settings > Webhooks while the phone channel is active.

Payload

Key	Type	Description
eventType	string	Event type
chatbotId	string	Agent ID
payload	Object	Payload of the event. Learn more

Event types

These are the list of events supported in webhooks:

leads.submit : When a customer submits their info (Name, Email, Phone, and any custom fields configured on the Collect Leads action) to your AI agent.
{action name}_collect_data.submit : When a customer submits the fields collected by a Collect Data action, where {action name} is the name of that action.
{action name}_custom_form.submit : When a customer submits a custom form, where {action name} is the name of that action.
phone_call.summary : When a phone call to your AI agent ends. Sent once per call, shortly after the caller hangs up, with an AI-generated summary of the conversation.

Event payload

The payload of each event:

leads.submit :

{
  conversationId: string,
  customerEmail: string,
  customerName: string,
  customerPhone: string,
  customFields: object // optional, only present when the Collect Leads action has custom fields
}

customFields is keyed by the field names configured on the Collect Leads action, e.g. { "Company name": "Acme", "Team size": 12 }. It is only sent when the action collects custom fields (conversational mode).

{action name}_collect_data.submit :

{
  conversationId: string,
  customFields: object // keyed by the field names configured on the Collect Data action
}

{action name}_custom_form.submit :

{
  conversationId: string,
  data: object, // the submitted form fields, keyed by field name
  error: string | null // set when an attachment upload failed
}

phone_call.summary :

{
  conversationId: string,
  callSummary: string,     // Generated summary of the call
  duration: number, // call length in seconds
  callerNumber: string,    // caller's phone number as presented by the carrier
  calledNumber: string     // your agent's number that the caller dialed, in E.164
}

callSummary can be an empty string if a summary could not be generated for the call. callerNumber may arrive in national format rather than E.164, depending on the carrier. calledNumber is the number on your account that received the call, webhooks are subscribed per AI agent, so use it to tell which line was dialed when one AI agent answers several numbers.

Receiving the 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-chatbase-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-chatbase-signature found in the request headers. If the are identical then the request is from Chatbase.

Next.js

import crypto from 'crypto'
import {NextApiRequest, NextApiResponse} from 'next'
import getRawBody from 'raw-body'

// Raw body is required.
export const config = {
  api: {
    bodyParser: false,
  },
}

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

    if (typeof SECRET_KEY != 'string') {
      throw new Error('No secret key found')
    }

    const rawBody = await getRawBody(req)

    const requestBodySignature = sha1(rawBody, SECRET_KEY)

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

    const receivedJson = await JSON.parse(rawBody.toString())

    console.log('Received:', receivedJson)

    /*
    Body example for leads.submit event
    {
      eventType: 'leads.submit',
      chatbotId: 'xxxxxxxx',
      payload: {
        conversationId: 'xxxxxxxx',
        customerEmail: 'example@chatbase.co',
        customerName: 'Example',
        customerPhone: '123',
        customFields: {
          'Company name': 'Acme',
          'Team size': 12
        }
      }
    }
    */

    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')
}

export default webhookHandler

Node.js

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-chatbase-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: 'example@chatbase.co',
        customerName: 'Example',
        customerPhone: '123',
        customFields: {
          'Company name': 'Acme',
          'Team size': 12
        }
      }
    }
    */

    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')
}

Getting Started

JavaScript Embed Features

Advanced Integration

Widgets

API v1 Reference

Webhook API Guide

Webhook API Guide

Create a webhook

Payload

Event types

Event payload

Receiving the request

​Webhook API Guide

​Create a webhook

​Payload

​Event types

​Event payload

​Receiving the request

Webhook API Guide

Create a webhook

Payload

Event types

Event payload

Receiving the request