Use Webhooks to Post Data to Third-Party APIs

Overview

Medallia Experience Cloud is a platform built for action; after all, the wealth of signals our platform collects is only as valuable as what you do with it. Because actions occur across a broad suite of enterprise software, Experience Cloud can trigger external workflows in near-real-time, by connecting to almost any stateless REST API.

Webhooks are triggered calls to an external system’s API. Webhooks enable you to define custom triggers and API request details - on a schedule or in real-time when a feedback or user record is created or updated.

Example Use Case

• When an employee gives negative feedback about an interaction with the IT team, create a new case in ServiceNow for IT to follow up right away.

API Used

• Webhooks

Triggers

Select a set of triggering fields and apply a matching condition, then select whether to trigger on record creation, record update, or both.

For the example case above, you might set the following trigger:

Data object: Survey
Trigger an event on record creation: false
Trigger an event on record update: true
Triggering fields: Status, Transactional Satisfaction
Matching condition: Status = Completed and Transactional Satisfaction = 0

This will trigger an outbound API call when a survey gets updated to Completed status with a Transactional Satisfaction of 0.

Authentication

Webhooks support calling external APIs that require authentication. Supported authentication protocols include OAuth 2.0, HTTP Basic Authentication, and other shared-token forms of authentication. When using OAuth 2.0, set your token endpoint and request credentials; Experience Cloud will retrieve an OAuth token when the first call is triggered and refresh it when necessary.

Authorization: Basic YmF0bWFuOnJvYmlu

// Inject a Base64 encoding library
var Base64 = {characters:"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=",encode:function(a){Base64.characters;var r="",c=0;do{var e=a.charCodeAt(c++),t=a.charCodeAt(c++),h=a.charCodeAt(c++),s=(e=e||0)>>2&63,A=(3&e)<<4|(t=t||0)>>4&15,o=(15&t)<<2|(h=h||0)>>6&3,B=63&h;t?h||(B=64):o=B=64,r+=Base64.characters.charAt(s)+Base64.characters.charAt(A)+Base64.characters.charAt(o)+Base64.characters.charAt(B)}while(c<a.length);return r}};

// Set variables for maintainability
var username = "batman";
var password = "robin";

// Encode the String for the header
return {
  "Authorization": "Basic " + Base64.encode(username + ":" + password)
};

Define the Request

Define a request URL, headers, and body to align with the target API’s spec. These can all be defined statically with basic text or generated dynamically using JavaScript. Pipe in field values from the triggering record. For example, if we create ServiceNow^® cases for negative feedback, we might populate the case description with certain comment fields, the employee’s email address, and/or the customer's name.

// This JavaScript can be used to support either single-record
// or batch/bulk handling

// This function return the JSON to create a single record in a
// ticket tracking system
var getPayload = function(record) {
	return {
		"fields": {
			"project": {
				"key": "PRJ"
      },
			"summary":"[Medallia] Issue from customer feedback",
			"description": (
      	"A customer has provided feedback.\n\n" +
      	"Likelihood to recommend: " + record.k_bp_main_score_scale + "\n" +
        "Email: " + record.e_email + "\n\n" +
      	"Please contact this customer within 2 days and log the outcome " +
      	"in this issue."
      ),
			"issuetype":{
				"name":"Task"
			}
		}
	};
};

// Get an array of all the feedback objects that are sent
// to the webhook. When not batching, this will be a
// single-element array.
var records = data.changedEntities;

// Process the record.  When in batch-mode, this is typically done
// using a for() loop.
var payload = getPayload(record[0]);

// Write the JSON payload to the request buffer using write(),
// remembering to stringify it first
write(JSON.stringify(payload));

Response Handling

Retrieve metadata from the API response and write it back to the triggering record using Medallia’s data transformation (ETL) layer. This enables reporting on successful and failed calls and enriching the Medallia record with additional data like point-of-sale transactional details or customer demographic information.

In the example code below, we perform the following response processing:

• If the request was successful, parse the response, and write the ID of the issue created in the ticket tracking system to the feedback record by directly calling an Import API processor.
• Otherwise, update the feedback object with any error message.

var requestBody = JSON.parse(http.getRequestBodyUtf8());

var responseBody = http.getResponseBodyUtf8()
	? JSON.parse(http.getResponseBodyUtf8())
	: {};

var responseStatusCode = http.getResponseStatusCode();

var record = data.changedEntities[0];

if (responseStatusCode == 200) {
	// Process the response from a successful request and
	// build the data structure to pass into the Import
  // API processor
  
	write(JSON.stringify({
		"medalliaRecordId" : record.a_surveyid,
		"ticketSystemSynced": 1,
		"ticketSystemSyncStatusCode": responseStatusCode,
		"ticketSystemRecordId": responseBody.ticketId
	}));
} else {
  // Process the response from an unsuccessful request
  write(JSON.stringify({
		"medalliaRecordId" : record.a_surveyid,
		"ticketSystemSynced": 2,
		"ticketSystemSyncStatusCode": responseStatusCode,
		"ticketSystemSyncError": responseBody.errorMessage
  }));
}

Other Settings

Medallia Webhooks support several other administrative settings. You can set a maximum batch size or the maximum number of concurrent threads. Set a number of retries and wait time between to define a retry policy for failed calls.

📘

Webhooks support calling bulk-ingestion APIs

To better support large-scale integrations, you can configure webhooks to send multiple records in a single call. This enables the best efficiencies when transferring large amounts of data from Medallia Experience Cloud to your third-party systems. See the Medallia Experience Cloud product documentation for more details.

Conclusion

Just as Custom Import APIs can flexibly accept data objects from most enterprise systems, Webhooks flexibly send data to almost any modern REST API. Webhooks are a powerful tool to enable seamless cross-platform workflows by leveraging your existing APIs.