Introduction

Hi Marley offers webhooks that carriers can subscribe to that will automatically trigger an action (e.g upload transcript to SFTP) based on the indicated event in Hi Marley (e.g case closure).

By enabling this type of custom configuration carriers have an advantage in how they can integrate with data from Hi Marley.

From time to time as Hi Marley releases new features additional fields will be added to API responses and webhook payloads. API users and Webhook consumers should be flexible enough to accept additive changes to the payload. Any breaking changes (meaning changes to the structure of the payload, removal of fields or events, and changes to datatypes) will be handled with versioning of APIs and webhooks.

Public Technical Documentation available on Postman

Available Webhooks
Subscribing to a Webhook
View Subscribed Webhooks
- Example Response
Removing a Webhook
Query and Retry Webhooks
Hi Marley Webhook IP Addresses
Other Integration related Overviews

Available Webhooks

Table of all available webhooks sorted by the Hi Marley Event that triggers the webhook action.

Hi Marley Event	Webhook Actions Available
Case Closed (via API or Webapp)	Push Case Transcript to Hi Marley SFTP Site (ID 3)
	Email Case Transcript or Media (ID 8)
	POST Case Transcript (via JSON Payload) to HTTP(s) Address (ID 11)
	POST Case Data (as JSON Payload) to HTTP(s) address (ID 10)
	Send Survey to User (ID 9)
Case Created (Via API or Webapp)	POST Case Data (as JSON Payload) to HTTP(s) address (ID 20)
Case Reopened (via API or Webapp)	POST Case Data (as JSON Payload) to HTTP(s) address (ID 18)
User Opt In	Post User Data to HTTP(s) Address (ID 2)
User Opt Out	Post User Data to HTTP(s) Address (ID 1)
Message Received or Sent in Hi Marley	Post Message Data + Case & Customer Data to HTTP(s) Address (ID 14)
User Sends a media file in Hi Marley (image, file, video)	Push Media File to Hi Marley SFTP Site (ID 15)
Scheduled Push (Daily or Weekly)	Push Modified Transcripts to SFTP Site (ID 4)
Case Note Created	Post Case Note to HTTP Address (ID 16)
Case Note Updated	Post Case Note Update to HTTP Address (ID 17)
Inbound Chatbot Flow Complete	Post Chatbot Data to HTTP Address (ID 19)
Message Updated	Needs Attention (Event ID 22)

Subscribing to a Webhook

Carriers can subscribe to a Hi Marley webhook using our POST/webhooks/register endpoint with the request payload associated to the specific webhook (request examples in our Postman docs).

Carriers can subscribe to any number of webhooks (even multiple of the same type) depending on where they need to send Hi Marley data.

Example Subscription

{
    //ID Associated to Event
    "EVENT_ID": 14,
    //Server Address that is listening for POST Requests from Hi Marley
    "HTTP_POST_ADDRESS": "https://webhook.site/bbd497f6-fa57-411e-b116-0227c4fd5bd4",
    //Headers to include with each POST request
    "HEADERS": {
        "key": "value",
        "key1": "value1"
    },
    "FILTER_BY": "value" //if criteria defined here is not met, then Webhook will not trigger.
}

Webhook Filters

When Subscribing to a Hi Marley Event you have the ability to Filter the Webhook from triggering if the Filter criteria defined in the Subscription is not met, thus preventing the Webhook from triggering/Posting data to the address defined in the Subscription.

Applicable Webhook Events to apply Filter:

EVENTS: 10, 11, 14, 18, 20, 22, 23, 24, 25, 26, 27, 28, 31

Available Filters	FILTER_BY: "value"	Complete Example
Case Brand	"caseData.brand:value"	"FILTER_BY":"caseData.brand:Hi Marley"
Case Line of Business	"caseData.brand:value&caseData.lineOfBusiness.type:value.lineOfBusiness.subType:value"	"FILTER_BY":"caseData.brand:Hi Marley&caseData.lineOfBusiness.type:auto&caseData.lineOfBusiness.subType:personal"
Case State	"state:value"	"FILTER_BY":" "state:open"
Case Type	"caseType:value"	"FILTER_BY":"caseType:claim"
Case Creation Source	"creationSource:value"	"FILTER_BY":"creationSource:PublicApi"

EVENT: 21

Available Filters	FILTER_BY: "value"	Complete Example
Case Brand	"case.caseData.brand:value"	"FILTER_BY":"case.caseData.brand:Hi Marley"
Case Line of Business	"case.caseData.brand:value&caseData.lineOfBusiness.type:value.lineOfBusiness.subType:value"	"FILTER_BY":"case.caseData.brand:Hi Marley&case.caseData.lineOfBusiness.type:auto&case.caseData.lineOfBusiness.subType:personal"
Case State	"case.state:value"	"FILTER_BY":" "case.state:open"
Case Type	"case.caseType:value"	"FILTER_BY":"case.caseType:claim"
Case Creation Source	"case.creationSource:value"	"FILTER_BY":"case.creationSource:PublicApi"

Webhook Authentication

Basic Authentication

The Hi Marley webhooks can be configured to send static basic auth tokens to your system. This token can be subscribed as a part of the header.

{
  "EVENT_ID": 10,
  "HTTP_POST_ADDRESS": "https://webhook.site/c30b8e85-b875-4225-8660-77c7926dd7893",
  "HEADERS": {
    "Authorization": "myToken3118yfj8134feda"
  }
}

OAuth 2.0

Hi Marley webhooks support Oauth 2.0 for outbound authorization integrations with any system that accepts Oauth 2.0. Grant-types are supported by Hi Marley webhooks for outbound integrations as defined by the receiving system.

Grant-Types currently supported for Outbound integration:

Password
Client Credentials

Hi Marley caches/uses the token per webhook subscription until the indicated expiration time is reached. Once Hi Marley caches the token, the following elements will be added to the webhook subscription:

"expires_at":"TimeStamp of Expiration",
"access_token":"Bearer Token"

For more information on OAuth 2.0, please refer to the official OAuth site.

In addition to the standard OAuth 2.0 fields, you can configure the Authorization section to customize the token retrieval call to your OAuth server. The two customization options are below:

optional_params: Array of Authorization parameters that are not required by your server. Can be used to not require a client_id or client_secret.
additional_headers: Static headers that will be added to each token retrieval call.

Example OAuth 2.0 Webhook Subscription - Client Credentials Grant Type

{
  "EVENT_ID": 10,
  "HTTP_POST_ADDRESS": "https://carrier_server.io/services/himarley",
  "HEADERS": {
    "Authorization": {
      "type": "OaUth2",
      "grant_type": "client_credentials",
      "client_id": "{{client_id}}",
      "client_secret": "{{client_secret}}",
      "scope": "{{required scope}}",
      "token_url": "https://authentication_server.io/services/oauth2/token/clientcredentialswithexpiry",
      "audience": "https://audienceUrl"
    }
  }
}

Example OAuth 2.0 Webhook Subscription - Password Grant Type

{
  "EVENT_ID": 10,
  "HTTP_POST_ADDRESS": "https://webhook.site/c30b8e85-b875-4225-8660-77c7926dd7893",
  "HEADERS": {
    "Authorization": {
      "type": "OaUth2",
      "grant_type": "password",
      "client_id": "{{client_id}}"",
      "client_secret": "{{client_secret}}",
      "token_url": "https://test.salesforce.com/services/oauth2/token",
      "username": "{{username}}",
      "password": "{{password}}"
    }
  }
}

The initial request to your authorization server will be sent as a POST with the header Content-Type: application/x-www-form-urlencoded. All parameters defined in the authorization object of the webhook subscription will be included in the body of this request.

Example OAuth 2.0 POST to Authorization Server

POST https://authentication_server.io/services/oauth2/token/clientcredentialswithexpiry
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id={{client_id}}&
client_secret={{client_secret}}&
scope={{required scope}}&
audience=https://audienceUrl

View Subscribed Webhooks

Carriers can view their existing webhook subscriptions using our GET/webhooks/subscribed endpoint. This will return each corresponding subscriptionID that can be used to remove a webhook subscription.

Example Response

{
  "subscriptions": [
    {
      "REGISTERED_PAYLOAD": {
        "EVENT_ID": 11,
        "HTTP_POST_ADDRESS": "http://mywebaddress.com/transcripts",
        "HEADERS": [
          {
            "key": "value",
            "key1": "value1"
          }
        ]
      },
      "SUBSCRIPTION_ID": "<unique id>",
      "EVENT": "CLOSE_CASE"
    }
  ]
}

Removing a Webhook

Carriers can remove a registered webhook using the subscriptionID in our DELETE/webhooks/unregister/{subscriptionID} endpoint.

Hi Marley Webhook IP Addresses

Please add the below Hi Marley IP Addresses to your allow list to ensure webhooks are not blocked by your network.

UAT

18.233.13.106

Production

18.204.115.246
18.211.217.22
54.157.144.172

Other Integration related Overviews

Webhook Specific Guides (Section): Dive into specific Webhooks to learn more them
API Overview: Learn more about the Hi Marley Public REST API
SFTP Overview: Learn more about the Hi Marley SFTP site offered to all of our customers for transcript and media uploads.

Are we missing something? Any Questions?

This documentation covers some of the key aspects of our webhooks, and use cases. Our documentation is always changing and growing as we learn what information is useful for our customers.

Please feel free to contact us with any questions around integrations that may not be addressed in this article

Webhooks Overview