Webhooks

Webhooks are a way for websites or applications to send real-time notifications to other websites or applications. They are a useful tool for automating workflows and integrating different services. When an event occurs on one website or application, a webhook sends a payload of data to a specified URL on another website or application. This allows the receiving website or application to take action based on the data received. In this section, we will explore how to set up and use webhooks within ChatBotKit.

Step-by-step Setup

1. Navigate to the Webhooks section of ChatBotKit.
2. Click on the "Create Webhook" button.
3. Setup a name and description for your webhook.
4. Set up a request for your webhook. This can be a URL or a full HTTP request that includes the method, URL, and headers.
5. Select the events that you want to observe with your webhook.
6. Click on the "Save" button to create your webhook.
7. Once your webhook is created, take note of the Secret. This secret is used to validate incoming web requests.

Validating Incoming Webhook Requests

To ensure that incoming webhook requests are authentic, ChatBotKit uses a header called X-Hub-Signature. This header contains a hash of the request body using a secret key that you specify during webhook setup. To validate incoming requests, you should perform the following steps:

1. Retrieve the value of the X-Hub-Signature header from the incoming request.
2. Using the same secret key that you specified during webhook setup, compute the HMAC SHA-256 hash of the request body (you can extract the algorithm from the X-Hub-Signature header).
3. Compare the computed hash to the value of the X-Hub-Signature header. If they match, the request is authentic.

Here's an example implementation of this validation process in Node.js:

import crypto from 'crypto'

function validateWebhookRequest(secret, body, signature) {
  const [algorithm, hash] = signature.split('=')
  
  const hmac = crypto.createHmac(algorithm, secret)
  
  const computedSignature = `${algorithm}=${hmac.update(body).digest('hex')}`

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(computedSignature))
}

In this example, secret is the secret key that you specified during webhook setup, body is the body of the incoming request, and signature is the value of the X-Hub-Signature header. If the function returns true, the request is authentic.

Here's an example implementation of this validation process in JavaScript using the Web Crypto API:

async function validateWebhookRequest(secret, body, signature) {
  const [algorithm, hash] = signature.split('=')
  
  const encodedSecret = new TextEncoder().encode(secret)
  
  const key = await window.crypto.subtle.importKey('raw', encodedSecret, 'HMAC', true, ['sign'])
  
  const encodedBody = new TextEncoder().encode(body)
  const computedHash = await window.crypto.subtle.digest(algorithm, encodedBody)
  
  const hmac = await window.crypto.subtle.sign('HMAC', key, computedHash)
  
  const computedSignature = `${algorithm}=${Array.from(new Uint8Array(hmac)).map(byte => byte.toString(16).padStart(2, '0')).join('')}`
  
  return computedSignature === signature
}

In this example, secret is the secret key that you specified during webhook setup, body is the body of the incoming request, and signature is the value of the X-Hub-Signature header. If the function returns true, the request is authentic.

By validating incoming webhook requests in this way, you can be sure that the requests are coming from ChatBotKit and have not been tampered with in transit.