# Webhooks

While Lynn's AI-powered chatbots bring significant value by automating customer interactions, it's essential to recognize that they work within the current boundaries of AI technology.

With Lynn, there are several effective methods to address these challenges and ensure customer satisfaction by seamlessly transitioning them to human assistance when the AI encounters limitations. Let's explore how you can leverage Lynn's features to achieve this.

The guide provides you with the capability to configure webhooks to receive a <mark style="color:red;">`POST`</mark> request when a requirement for a human handover event is triggered.

## Setup

The image shows a user interface for setting up handover rules in Lynn.

For the section to add a new handover rule, you should fill in details such as:

* **Title**: The name or identifier for the new rule.
* **Rule Type**: Options to select whether the handover is a webhook rule (as in the example shown) or an email rule.
* **Webhook URL**: The field where the user would enter the endpoint URL for Lynn to send data to when the handover is triggered.

<figure><img src="https://2762017608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWsuD6nsscVhXqYf6UuRj%2Fuploads%2FsbdHOIGxLywTT06B878h%2FUntitled.png?alt=media&#x26;token=aebb5425-0f67-45d2-8fd7-1c5d3b71b9fb" alt=""><figcaption></figcaption></figure>

* **Secret Key**: Once you've set up the handover rule, you'll notice a part of the screen that keeps the secret key just out of sight. Think of this key as a secret handshake between Lynn and the endpoint. This key is used to sign requests to verify their authenticity.

## Payload

| **Key**          | Type   | Description                                                        |
| ---------------- | ------ | ------------------------------------------------------------------ |
| `conversationId` | String | Identifier for the conversation.                                   |
| `workspaceId`    | String | Identifier for the workspace.                                      |
| `widgetId`       | String | Widget identifier to identify the widget that triggered the event. |
| `messages`       | Array  | An array of messages that exchanged in the conversation.           |
| `createdAt`      | String | Timestamp for when the message was created.                        |
| `updatedAt`      | String | Timestamp for when the message was last updated.                   |
| `contactEmail`   | String | Email address provided by the user who need the support.           |

Example:

```json
{
  "conversationId": "clP5fVfvHISpzpLkJub2",
  "workspaceId": "04JchTJQCSG4GyYobqi1",
  "widgetId": null,
  "messages": [
    { "text": "Hi", "senderRole": "human" },
    {
      "resources": [],
      "text": "Hello! How can I assist you today?",
      "senderRole": "lynn"
    },
    { "text": "I need human support", "senderRole": "human" },
    {
      "resources": [],
      "text": "Sure, would you be able to share your email address for our awesome support team to get back?",
      "senderRole": "lynn"
    },
    {
      "text": "Here's my email address - vinsurakumuthu@gmail.com.",
      "senderRole": "human"
    },
    {
      "resources": [],
      "text": "Well received, thank you!",
      "senderRole": "lynn"
    }
  ],
  "createdAt": "2023-11-23T07:48:23.119Z",
  "updatedAt": "2023-11-23T07:48:59.400Z",
  "contactEmail": "vinsurakumuthu@gmail.com",
  "customMetadata": null
}
```

For testing the functionality of your webhook, you can use [webhook.site](https://webhook.site/) as a convenient tool to simulate receiving and inspecting the requests.

<figure><img src="https://2762017608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWsuD6nsscVhXqYf6UuRj%2Fuploads%2FPK2UoXgU4aSIfBrxCtTL%2FUntitled%201.png?alt=media&#x26;token=3452f4ce-4bbb-47db-b30a-0b04b06b4a72" alt=""><figcaption></figcaption></figure>

## Receiving the Request

You can easily get the information you need from the request body, just like you would with any request. However, for added security and to prevent spam from people who are aware of your endpoint, it's a good idea to check the `x-lynn-hmac-sha256` in the request header. This helps ensure that only legitimate requests are processed.

To verify the data's authenticity, encrypt the entire request body using `HMAC-SHA256` with a `secret key` that Lynn’s admin portal. Then compare the generated signature with the `x-lynn-hmac-sha256` value in the request headers. If they match, it confirms the message's legitimacy.

The following Next.js code example demonstrates a secure way to handle webhook requests.

[Next.js](https://support.lynn.chat/webhooks/next.js)