Webhooks Management

What are webhooks?

A webhook is a means of proactively informing one system when there is a change or event in another one. At Mainstay, webhooks allow a partner to receive notifications of escalations to an external API (in addition to email).

Configuration

To configure a new webhook, visit https://app.mainstay.com/settings/api-tokens (Settings > Mainstay API). This table shows a list of all configured webhooks.

• Name - a custom name given to this configuration
• Enable - a boolean toggle that sets whether to send data to this webhook URL
• URL - the web address of the external system that is expecting data
• Event Type - the kind of event that would be sent to this URL; at present, this is only Escalations
• Revoke Access - remove this configuration

Creating a Configuration

1. Click Create New to configure a webhook.
2. Enter a custom Name for this  configuration and the exact URL that will receive the data.
   • 
3. Click Create Shared Secret
4. Copy this Shared Secret to a safe place. This is used for verifying that data received at this URL was sent from Mainstay.
   • 
5. To enable or disable this configuration, click the toggle in the Enabled column.

Removing a Configuration

1. Click Revoke Access to pull up a confirmation screen.
   • 
2. Click Yes, Revoke to permanently delete this configuration.
3. Note that it is not possible to edit a configuration. If you need to change the Name or URL, or if you need to reset the Shared Secret, simply delete the existing configuration and create a new one.

Escalations Rules

To configure an escalation rule, visit https://app.mainstay.com/settings/escalation (Settings > Email Forwarding & Escalations). See the support article on Email Forwarding & Escalations to learn more about manual and automatic escalations.

If the webhooks feature is available on your account - regardless of whether you have any enabled configurations - you will see an informational banner above both the Manual Forwarding Suggestions and Automatic Escalation Rules tables:

You will also be able to configure rules without an email recipient - the field becomes optional:

All escalation events will send to all enabled webhook configurations. Even if there is an email recipient, an escalation event will still be sent to your webhook configurations.

You can also have campaign Script escalations and responses to Script questions escalate to webhooks if you so choose:

Escalations Event Payload

Here is an example of an automatic escalation sent to a webhook URL as a POST request:

{
  "topic_schema_version": "2.0",
  "topic": "escalation.triggered",
  "event_id": "afe4be18-bfbe-4967-b9cd-f42d534f4862",
  "event_time": "2022-05-27T17:55:22.054895Z",
  "attempts": 1,
  "data": {
    "escalation_id": "xzzWPnuiewF4cJW5C",
    "contact_id": "5e41985fe64395007d593825",
    "message_id": "85564b211327403ca2e67bf9f0cac5f5",
    "escalated_message": "test from James M die",
    "institution_id": "productTest",
    "occurred_at": "2022-05-27T17:55:13.126751Z",
    "non_english_translation": null,
    "escalation_type": "sensitiveMatch",
    "conversation_link": "https://app.mainstay.com/conversations/5e41985fe64395007d593825",
    "contact_information": {
      "mainstay_id": "5e41985fe64395007d593825",
      "first_name": "James",
      "last_name": "Mayr",
      "preferred_name": "Jimbo",
      "email": "james@mainstay.com",
      "phone": "5553141592",
      "enrollment_id": "abc",
      "crm_id": "xyz",
      "custom_fields": {
        "favoritecolor": "blue"
      },
      "latest_chat_history": [],
      "logs": [
        {
          "incoming": true,
          "message_body": "test from James M die"
        },
        {
          "incoming": false,
          "message_body": "You said die and I'm programed to treat that language seriously. If there's an emergency, call 911"
        }
      ]
    }
  }
}

Note that event_id and event_time refer to Mainstay's attempt to send this payload to the webhook URL, while data.escalation_id and data.occurred_at refer to the escalation event itself - in this case, the bot recognizing that the incoming message contained the sensitive word "die".

In addition to this payload, the following headers are included:

{
  "Content-Type": "application/json",
  "Mainstay-Signature": str,
  "Mainstay-Timestamp": str(seconds-since-epoch),
}

This mainstay-signature value is derived from the Shared Secret and the payload as a JSON Web Token. This can be used to ensure that the data is truly coming from Mainstay (without revealing the Shared Secret). See below for a technical guide.

Creating A Webhook Endpoint

A webhook endpoint is an HTTP or HTTPS endpoint on your server with a URL. Note that once your new webhook endpoint is publicly accessible, it must be HTTPS.

Set up an HTTP endpoint on your local machine which will do the jobs of verifying the incoming POST request signatures, consuming the request payload, and returning a response to Mainstay.

The incoming request payload has the headers and schema as detailed above.

The webhook URL should send return a response with one of the following shapes back to Mainstay.

Successful requests:
{"statusCode": 200, "body": {"message": str}}




Failed requests:

400 - Bad request
{"statusCode": 400, "body": {"error": str}}

500 - Something else went wrong
{"statusCode": 500, "body": {"error": str}}