🏉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 POST 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.

• 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:

{
  "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 - [e-mail].",
      "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": "[e-mail]",
  "customMetadata": null
}

For testing the functionality of your webhook, you can use webhook.site as a convenient tool to simulate receiving and inspecting the requests.

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