Overview

Thena's webhook functionality provides a seamless way to stay informed about specific events in real-time, like request creation or updates. By integrating these webhooks into systems such as data lakes, CRMs, and other applications, you can instantly process and act upon these events. This real-time synchronization empowers businesses to enhance their operations and customer engagement.

Setting Up Thena Webhooks

  • Go to the Thena dashboard: https://app.thena.ai/settings?tab=integrations
  • Navigate to Global Settings -> Integrations.
  • Select Webhooks -> Add Integration.
  • A dialog will appear. Input your Thena Access Key.
  • Specify the webhook endpoint where you wish to receive the events.
  • Optionally, specify a header authentication value under the header key "authorization" if you want additional security.

Use the toggles within the modal to enable or disable specific webhook events, such as 'request created' and 'request updated'.

Webhook Event Types

Request Created: Triggered when a new request is made.
Request Updated: Triggered when an existing request is updated, including status changes, assignment modifications, CSATs, and other metadata. This webhook is not triggered for each message on the customer or internal thread.
Request Escalated: Triggered when a request is escalated manually using the ‼️emoji.

When are the Webhooks fired

If you have enabled all the 3 webhooks that we support, below are the webhooks you will get up:

EventWebhook
User Message detected as a requestRequest Created
Request Breached SLA of first response timeRequest Updated
Request auto assigned to a user as they replied to the requestRequest Updated
Customer/ User manually escalates the RequestRequest Updated
Request Escalated

Webhook Payload Fields

FieldTypeDescription
actionStringType of action, e.g., "UPDATE" | "CREATE"
requestObjectDetails about the request
AI_generatedTagsArrayAI generated tags linked to the request
AI_requestSentimentStringAI-generated sentiment analysis result
AI_requestSummaryStringAI-generated summary of the request
AI_requestTitleStringAI-generated title for the request
AI_requestUrgencyStringAI-determined urgency of the request
activityArrayList of activities related to the request
assignedByObjectInformation about who assigned the request
assignedToObjectInformation about who the request is assigned to
channelIdStringUnique ID for the communication channel
channelNameStringName of the communication channel
closed_byObjectInformation about who closed the request
closed_onStringTimestamp when the request was closed
configuredFieldValuesObjectConfigured values for custom fields
createdAtStringTimestamp when the request was created
customer_nameStringName of the customer who made the request
descriptionStringDescription or content of the request
feedbacksStringFeedback given by the customer
permalinkStringPermanent link to the request
replyCountNumberCount of replies for the request
requestIdNumberUnique ID for the request
requestLinkStringDirect link to view the request
requestorObjectInformation about the individual making the request
senderObjectInformation about the request sender
statusStringCurrent status of the request
team_idStringUnique ID of the team handling the request
team_nameStringName of the team handling the request
updatedAtStringTimestamp of the last update to the request
first_response_atStringTimestamp of the first response in the customer thread
last_reply_by_customer_tsStringTimestamp of the laste response by the customer
last_reply_by_vendor_tsStringTimestamp of the laste response by the vendor
external_linksArrayDetails of the external links attached to the request
crm_dataArrayName and id of the CRM Account linked to the account in Thena
merged_requestsArrayDetails of the merged requests

Sample Webhook Payload

Here's a more comprehensive payload for the "Request Updated" webhook event:

{
    "action": "UPDATE",
    "request": {
        "AI_generatedTags": ["Lorem", "Ipsum"],
        "AI_requestSentiment": "Neutral",
        "AI_requestSummary": "Dolor sit amet, consectetur adipiscing.",
        "AI_requestTitle": "Adipiscing Elit Ipsum",
        "AI_requestUrgency": "Medium",
        "activity": [
            {
                "id": "LOREM12345",
                "text": "<p>Lorem ipsum dolor sit.</p>",
                "ts": "1692826409.902529",
                "user": {
                    "id": "LOREM12345",
                    "name": "lorem.ipsum"
                }
            }
            // ... other activity data
        ],
        "assignedBy": {
            "email": "[email protected]",
            "emailDomain": "thena.ai",
            "id": "IPSUM67890",
            "name": "lorem.ipsum_assigner"
        },
        "assignedTo": {
            "email": "[email protected]",
            "emailDomain": "thena.ai",
            "id": "DOLOR11121",
            "name": "assigned.to_name"
        },
        "channelId": "CHAN12345",
        "channelName": "thena-dev-lorem",
        "closed_by": {
            "email": "[email protected]",
            "emailDomain": "thena.ai",
            "id": "CLOSE98765",
            "name": "closer.name"
        },
        "closed_on": "2023-08-23T21:55:58.034Z",
        "configuredFieldValues": {
            "Product": [
                {
                    "name": "Product Lorem",
                    "value": "Product Ipsum"
                }
            ]
        },
        "createdAt": "2023-08-23T21:31:01.573Z",
        "customer_name": "Lorem Customer Ipsum",
        "description": "<p>Lorem ipsum dolor sit amet.</p>",
        "feedbacks": "<p>lorem.ipsum_customer gave 5 with additional feedback of Great Support!</p>",
        "internalAlert": {
            "channel": "CHANIPSUM789",
            "permalink": "https://lorem.slack.com/archives/CHANIPSUM789/p1692826261224619",
            "ts": "1692826261.224619"
        },
        // ... other internalNotes
        "isInternalHelpdesk": false,
        "isPrivateChannel": false,
        "permalink": "https://lorem.slack.com/archives/CHAN12345/p1692826255621649",
        "replyCount": 8,
        "requestId": "42",
        "requestLink": "http://localhost:3000/requests?requestId=42",
        "requestTs": "1692826255.621649",
        "requestor": {
            "email": "[email protected]",
            "emailDomain": "thena.ai",
            "firstName": "Lorem",
            "id": "REQ123456",
            "lastName": "Ipsum",
            "name": "requestor.name"
        },
        "sender": {
            "email": "[email protected]",
            "emailDomain": "thena.ai",
            "firstName": "Lorem",
            "id": "SEND654321",
            "lastName": "Ipsum",
            "name": "sender.name"
        },
        "status": "ASSIGNED",
        "team_id": "TEAM123456",
        "team_name": "Team Lorem Ipsum",
        "threadTs": "1692826255.621649",
        "updatedAt": "2023-08-23T22:51:21.912Z"
        "last_reply_by_customer_ts": "1714988657.758209",
        "last_reply_by_vendor_ts": "1714988666.871509",
        "first_response_at": "1714988615.667009",
        "external_links": [
          {
              "assignee": "Lorem ipsum",
              "created_at_utc": "Lorem ipsum",
              "description": "Lorem ipsum",
              "integration": "Lorem ipsum",
              "labels": ["Lorem ipsum", "Lorem ipsum"],
              "status": "Lorem ipsum",
              "title": "Lorem ipsum",
              "url": "Lorem ipsum"
          }
         ],
    			"crm_data": { 
      			  "name": "Lorem ipsum", 
  			      "crm_id": "Lorem ipsum" 
  			  },
    			"merged_requests": [
            {
                "title": "Lorem ipsum",
                "ts": "Lorem ipsum",
                "customer_channel_permalink": "Lorem ipsum",
                "internal_channel_permalink": "Lorem ipsum",
                "request_id": "Lorem ipsum"
             }
   				]
    }
}

Sample Escalation Webhook Payload

{
  "action": "REQUEST_ESCALATION_CREATED",
  "request": {
    "relationship_id": "loremipsum1",
    "installation_id": "loremipsum2",
    "activity": [],
    "internalNotes": [],
    "createdAt": "2024-02-29T03:09:11.697Z",
    "updatedAt": "2024-02-29T03:09:41.475Z",
    "team_id": "loremipsum3",
    "team_name": "Lorem Ipsum Team",
    "ts": "loremipsum4",
    "requestTs": "loremipsum5",
    "threadTs": "loremipsum6",
    "AI_requestTitle": "Lorem Ipsum Dolor Sit Amet",
    "AI_requestSummary": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "AI_requestSentiment": "Neutral",
    "AI_requestUrgency": "Low",
    "AI_generatedTags": [
      "Lorem Ipsum"
    ],
    "internalAlert": {
      "channel": "loremipsum7",
      "ts": "loremipsum8",
      "permalink": "https://loremipsum.slack.com/archives/loremipsum/ploremipsum"
    },
    "sender": {
      "name": "Lorem Ipsum Sender",
      "email": "[email protected]",
      "id": "loremipsum9",
      "firstName": "Lorem",
      "lastName": "Ipsum",
      "emailDomain": "ipsum.com"
    },
    "requestor": {
      "name": "Lorem Ipsum Requestor",
      "email": "[email protected]",
      "id": "loremipsum10",
      "firstName": "Lorem",
      "lastName": "Ipsum",
      "emailDomain": "ipsum.com"
    },
    "channelName": "lorem-ipsum-channel",
    "channelId": "loremipsum11",
    "isPrivateChannel": false,
    "isInternalHelpdesk": false,
    "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
    "replyCount": 0,
    "status": "LOREM_IPSUM",
    "permalink": "https://loremipsum.slack.com/archives/loremipsum/ploremipsum",
    "requestId": 1234,
    "requestLink": "http://localhost:3000/requests?requestId=1234",
    "assignedBy": {},
    "assignedTo": {},
    "closed_by": {},
    "escalation_type": "lorem_ipsum",
    "escalation_details": [
      {
        "escalationReason": "Lorem Ipsum Reason",
        "escalationMessage": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
        "escalationBusinessImpact": "Lorem Ipsum Impact",
        "escalationTs": "loremipsum12",
        "escalatedBy": {
          "name": "Lorem Ipsum",
          "slackId": "loremipsum13",
          "profileImg": "https://loremipsum.com/avatars/loremipsum.png"
        }
      }
    ],
    "configuredFieldValues": {},
    "feedbacks": "",
    "customer_name": "Lorem Ipsum Customer"
  }
}

FAQs

Webhooks

What can I use Thena webhooks for?

You can use Thena webhooks to forward events to data lakes, CRMs, and other systems for real-time synchronization and processing. This enables businesses to enhance their operations and engage customers effectively.

How real-time are the webhook events?

Thena webhooks are dispatched almost instantly after the event occurs, ensuring that you receive notifications in near-real-time.

How does Thena handle retries if my endpoint fails to process a webhook?

If Thena encounters a failure when sending a webhook, it follows a retry mechanism as outlined below:

  • 1st retry: Approximately 10 seconds after the initial attempt.
  • 2nd retry: Approximately 20 seconds after the 1st retry.
  • 3rd retry: Approximately 30 seconds after the 2nd retry.
  • 4th retry: Approximately 50 seconds after the 3rd retry.
  • 5th retry: Approximately 80 seconds after the 4th retry.

Ensure that your endpoint is capable of handling these retries. It's a good idea to log the incoming requests to monitor and identify any issues with the webhook deliveries.

Can I select which events I want to receive?

Yes, using the integration modal in the dashboard, you can choose to enable or disable specific events as per your requirements.

Is there a way to ensure the security of the webhooks being sent through?

Absolutely! You can specify an authentication header value to ensure that the incoming data is secure and from a trusted source.

I'm not receiving any webhook events. What could be the issue?

Ensure that the endpoint URL you provided is correct and can accept POST requests. Also, verify if the event you're expecting is enabled in the dashboard settings.

What should I do if my endpoint experiences downtime?

It's a good practice to have retry mechanisms on your server to handle webhook failures due to temporary outages. Ensure that your server responds with a 200 OK status for successful receipt of the webhook.

What is the purpose of the external_links field?

The external_links field provides additional resources related to the task or issue. It includes details such as the assignee, creation time, description, integration source, labels, status, title, and a URL.

What information is contained in the crm_data field?

The crm_data field includes CRM-related information such as the name and ID of the CRM entity. This helps link the webhook event to specific CRM records.

How is the merged_requests field utilized?

The merged_requests field lists customer support or help requests that have been merged. It includes the title of the request, a timestamp, permalinks to customer and internal channels, and a unique request ID.