An organization's webhooks can be configured by navigating to the Admin > Developer console. Click on Webhooks in the left-hand sidebar for access.

Configuration

Creating a Webhook

In the Webhooks section, click New Webhook found at the upper-right corner of the page. This will display a dialog where you can set your webhook status (enabled/disabled), give your webhook a name, and specify its endpoint (Payload URL). Click Create Webhook to submit your settings.

📘

Note

You can modify your settings at a later time.

Add Event Subscriptions

From the Webhooks portal's list view, click on the webhook you want to configure. This will take you to the Settings view where you can choose which event categories you would like to subscribe to.

Filter Webhook Event Subscriptions

Note that you can optionally add filtering to your webhook events to narrow down to a subset of events in which you're interested in, based on the available properties below:

Use the image below as a guide for setting up filters for your specific Webhook Events:

Managing Webhook Secrets

When you create a webhook, the system automatically issues a secret which is used for authenticating webhook events. From the webhook detail view, you may access the secret as well as reissue the secret (e.g. if you suspect it has been compromised).

📘

Note

For more information about delivery verification, see our Webhook Delivery Verification guide.

Deleting a Webhook

Deleting a webhook can be done either by clicking on the "..." icon on a Webhook listing, or by pulling up the Settings view and clicking on 'Delete Webhook'.

Deliveries

MedChat keeps a record of all attempted deliveries, whether successful or failed, for 7 days. This can be useful for troubleshooting webhook connectivity, and also allows developers to resend deliveries (e.g. if they fail and need to be sent again).

Viewing Deliveries

To view historical deliveries, access the details for your webhook and click the Deliveries tab at the top.

Each delivery in the list can be expanded to show details about the delivery request as well as the response received by the system.

Redeliveries

Clients may have situations where they want to redeliver an event to their webhook. This is possible by expanding the delivery details and clicking the Redeliver button. The original delivery record will remain in the list, and we will attempt to deliver the same payload again.

Event Categories

Webhooks subscribe to individual event categories. An event category corresponds to one or more related event types.

Chat Status

Chat status events represent key points in a chat's lifetime.

ChatOpened

The ChatOpened event fires every time a chat is initiated in MedChat, whether the chat is routed to an agent or to a chat bot.

{
  "Type": "ChatOpened",
  "Timestamp": "2020-09-11T18:20:48.2678017Z",
  "OrgId": "<guid>",
  "ChatId": "<guid>"
}

ChatEnded

The ChatEnded event happens whenever the chat ends for any reason.

{
  "Type": "ChatEnded",
  "Timestamp": "2020-09-11T18:20:48.2678017Z",
  "OrgId": "<guid>",
  "ChatId": "<guid>",
  "ChatEndReason": "EndedByUser"
}

ChatArchived

ChatArchived events fire when an agent archives the chat from the agent UI.

{
  "Type": "ChatArchived",
  "Timestamp": "2020-09-11T18:20:48.2678017Z",
  "OrgId": "<guid>",
  "ChatId": "<guid>"
}

ChatTagged

ChatTagged events fire when a tag is added to a chat.

{
  "Type": "ChatTagged",
  "Timestamp": "2020-09-11T18:20:48.2678017Z",
  "OrgId": "<guid>",
  "ChatId": "<guid>",
  "Tag": "Tag 1",
  "Category": "Category A"
}

ChatTagDeleted

ChatTaggedDeleted events fire when a tag is deleted from a chat.

{
  "Type": "ChatTagDeleted",
  "Timestamp": "2020-09-11T18:20:48.2678017Z",
  "OrgId": "<guid>",
  "ChatId": "<guid>",
  "Tag": "Tag 1",
  "Category": "Category A"
}

Message Posted

This category is dedicated solely to MessagePosted events.

MessagePosted

This event fires every time a message is posted to the chat by any participant, whether the participant is a human or a bot.

{
  "Type": "MessagePosted",
  "Timestamp": "2020-09-11T18:20:48.2678017Z",
  "OrgId": "<guid>",
  "ChatId": "<guid>",
  "MessageId": "<guid>",
  "UserId": "<guid>",
  "MembershipType": "ExternalUser|Agent|Bot"
}

External Bots

This category represents events that apply to externally-implemented chat bots.

ExternalBotFlowTriggered

The ExternalBotFlowTriggered event fires when a MedChat bot execution encounters an instruction to transfer control to an external bot.

{
  "Type": "ExternalBotFlowTriggered",
  "Timestamp": "2020-09-11T18:20:48.2678017Z",
  "OrgId": "<guid>",
  "ChatId": "<guid>",
  "ChatBotId": "<guid>",
  "ExecutionId": "<guid>",
  "ChatBotName": "Appointment Scheduling Bot",
  "ExternalBotFlowStepIdentifier": "some-identifier"
}

Chat Context

This category represents events relating to changes in a chat's context.

Chat Context Updated

The ChatContextUpdated event fires when a chat's context changes.

{
  "Type": "ChatContextUpdated",
  "EventId": "<guid>",
  "ChatId": "<guid>",
  "OrgId": "<guid>",
  "Timestamp": "2022-06-09T14:20:44.8049692Z",
  "Updates": [
    {
      "Type": "UserInputAdded",
      "BlockId": "<string>",
      "MessageId": "<guid>",
      "RequestMessageId": "<guid>"
    }
  ]
}

Registered Chats

This category represents events relating to registered chats.

Registered Chat Started

The RegisteredChatStarted event fires when a chat is started from a registered chat.

{
  "Type": "RegisteredChatStarted",
  "Timestamp": "2020-09-11T18:20:48.2678017Z",
  "OrgId": "<guid>",
  "ChatId": "<guid>",
  "RegisteredChatId": "<guid>",
  "ReferenceCode": "Appointment Scheduling Bot"
}

User Verification Succeeded

The UserVerificationSucceeded event fires when the user successfully verifies his/her identity for a chat started from a registered chat.

{
  "Type": "UserVerificationSucceeded",
  "Timestamp": "2020-09-11T18:20:48.2678017Z",
  "OrgId": "<guid>",
  "ChatId": "<guid>",
}

User Verification Failed

The UserVerificationFailed event fires when the user fails to verify his/her identity for a chat started from a registered chat.

{
  "Type": "UserVerificationFailed",
  "Timestamp": "2020-09-11T18:20:48.2678017Z",
  "OrgId": "<guid>",
  "ChatId": "<guid>",
}

User Verification Abandoned

The UserVerificationAbandoned event fires when the user leaves the chat before he/she verifies his/her identity for a chat started from a registered chat.

{
  "Type": "UserVerificationAbandoned",
  "Timestamp": "2020-09-11T18:20:48.2678017Z",
  "OrgId": "<guid>",
  "ChatId": "<guid>",
}

Subscriptions

This category represents events relating to subscribing to and unsubscribing from SMS chats.

SMS Subscribed

The SmsSubscribed event fires when the user subscribes/opts-in to an SMS chat by texting "Start" (or one of the other opt-in keywords).

{
  "Type": "SmsSubscribed",
  "EventId": "<guid>",
  "Timestamp": "2022-11-14T22:46:46.2494108Z",
  "OrgId": "<guid>",
  "SmsChatId": "<guid>",
  "SenderPhoneNumber": "<the org's phone number>",
  "RecipientPhoneNumber": "<the patient's phone number>"
}

SMS Unsubscribed

The SmsUnsubscribed event fires when the user unsubscribes/opts-out from an SMS chat by texting "Stop" (or one of the other opt-out keywords) or when a text bot Opt Out of SMS step executes.

{
  "Type": "SmsUnsubscribed",
  "EventId": "<guid>",
  "Timestamp": "2022-11-14T22:46:46.2494108Z",
  "OrgId": "<guid>",
  "SmsChatId": "<guid>",
  "SenderPhoneNumber": "<the org's phone number>",
  "RecipientPhoneNumber": "<the patient's phone number>"
}

Retention Jobs

This category represents events relating to retention jobs.

Retention Job Completed

The RetentionJobCompleted event fires when a retention job has finished processing and an extract file is ready for download.

{
  "Type": "RetentionJobCompleted",
  "EventId": "<guid>",
  "Timestamp": "2022-11-14T22:46:46.2494108Z",
  "OrgId": "<guid>",
  "JobId": "<guid>"
}