JSON Event
Suite
Customer Experience
Employee Experience
Strategy & Research
Product
Qualtrics
What's on this page
Qtip: JSON Events are only available to users who have purchased access to the Qualtrics API. If you are interested in getting this feature, talk to your Account Executive or Account Services.
About the JSON Event
Have you ever wanted a request made on your website to trigger a ticket in Qualtrics? Have you ever wanted to create a seamless integration between Qualtrics and your own internal system? Have you ever wanted to trigger a task in the Workflows tab, but with an event that happens outside of Qualtrics?
JSON events allow external software to start workflows via HTTP request. Instead of waiting for an event in Qualtrics to trigger further action in the platform, you can simply configure a JSON event to receive requests from a third party.
Qtip: You must generate an API token before this feature is available to you. If you already have an API token, you do not need to generate a new one.
Attention: Setting up a JSON event requires advanced programming knowledge. Although our support team is happy to help with the basics of putting information into the event, we cannot provide support on the programming aspects. You can always try asking our community of dedicated users instead.
Limitations
The JSON event is not compatible with the following set-ups and configurations:
- Anything that is not HTTP (e.g., message queue, SMS).
- Outbound HTTP calls.
- Process XML (the XML request body will be ignored).
- Process anything other than JSON.
- Authenticate any way other than an X-API-TOKEN header or our modified HTTP basic auth. Qtip: OAuth and other forms of authentication are incompatible with JSON events.
- Any JSON parsing that cannot be satisfied by using JSONPath queries on the JSON body.
- Calls exceeding the API rate limit of 3,000 per minute.
- Payloads exceeding 100 KB.
- 10 manually input fields. Qtip: Once information is pulled in with event capture, it will be added to the JSON body. Event capture is the only way to add more than 10 fields.
Types of Auth Supported
Token-Based Auth / Header Auth
You can authenticate by passing your API token through the header of the request as X-API-TOKEN.
Example: In the following POST example, in cURL we specify the Base URL, the Content-Type, and the Token in the header. The Survey ID and format of export are specified in the body.
curl -X POST -H 'X-API-TOKEN: yourapitokenhere' -H 'Content-Type: application/json' -d '{
"surveyId": "SV_012345678912345",
"format": "csv"
}' 'https://yourdatacenterid.qualtrics.com/API/v3/responseexports'
HTTP Basic Auth
Basic Auth is usually a Base64 encoded version of username:password. However, for improved security, Qualtrics uses a Base64 encoded string of username:x-api-token.
To use Basic Auth, you must set headers on the HTTP request. The specific header is Authorization.
Example: Let’s say your Qualtrics username is demo@qualtrics.com and your API Token is f8gIK7G6GFH985Y4. First you’d write,
demo@qualtrics.com:f8gIK7G6GFH985Y4Then after Base64 encoding, this would appear as,
Basic ZGVtb0BxdWFsdHJpY3MuY29tOmY4Z0lLN0c2R0ZIOTg1WTQ=So the Authorization header you add to your HTTP request would have the value Basic ZGVtb0BxdWFsdHJpY3MuY29tOmY4Z0lLN0c2R0ZIOTg1WTQ=.
Qtip: Check out these tools for encoding base64 and decoding base64.
Setting Up a JSON Event
First, you will need to create a workflow. Go to the stand-alone Workflows page.
Qtip: You can also use JSON events in the Workflows tab in a project or in XM Directory. We only recommend adding a workflow to a specific project if they’re explicitly related (for example, you are distributing that project with the JSON event). The JSON event can be used in all workspaces except for imported data projects.
Make sure you’re in the Your workflows tab.
Click Create a workflow.
Select Started when an event is received.
Select the JSON event.
If you’d like, specify a Trigger summary, which should describe the purpose of the JSON event.
You will be given a URL. Use this to invoke your new workflow from outside Qualtrics, using Postman, your own internal system, or other similar applications. To copy it, click Copy URL.
By default, JSON events require authentication. If you want to allow unauthenticated requests, you can disable Require authentication by Qualtrics.
Now, you can define the event data. This will capture data from the inbound request. To start, click Advanced settings.
Qtip: For information about the Test section, see Capturing Events below.
On the box on the left, give the JSON field name. On the box on the right, give the location within the event data (HTTP request body).
Qtip: The locations must be in JSONPath format! See the table below for a quick guide to JSONPath Syntax.
To add another field, click Add a JSON field.
If you’d like to add a QUERY parameter, add them in the QUERY Parameters section. For more on what these parameters are and how they work in API, see our API Documentation on Parameters.
Warning: It is not advisable to pass personally identifiable data through QUERY parameters. Any personally identifiable information or sensitive data should be passed through the POST body whenever possible, as POST is more secure.
To remove a field, click the minus sign ( – ).
To save your changes, click Save.
Now you can add conditions and a task to your workflow by clicking the plus sign ( + ). Conditions determine when a workflow runs, while tasks are the result of the workflow. See the Building Workflows for more information.
Qtip: Click on your JSON event to change the parameters and JSON fields.
Attention: A JSON event can only be fired via API from the same account that created the event. If a different account is used to fire the API for a JSON event, you may still receive a 202-success API response, however this means that a valid API token was used to make a valid request, but does not necessarily mean that the correct API token was used, or that the JSON event was triggered correctly. If you receive a 202-success API message, you will want to check the platform to confirm the correct API was used.
Capturing Events
When you are creating an external API event, you may need to parse data from the post body. However, it can be difficult at times to parse this data. If you want to figure out what your external API is sending, follow these steps.
Click on your JSON event.
By default, the Capture JSON fields from the test results so they can be used as piped-text in other tasks in this workflow option will be enabled. This option makes it so that fields parsed into the body of the payload will be automatically available as piped text when you add your workflow tasks.
Click Run a new test.
You will see a message that Qualtrics is waiting to receive the event from your external system. Fire your external API.
Qtip: To cancel this test, click Cancel test.
If the test was successful, you will see the message Successfully connected to the server. The payload will be parsed and added to the window.
If desired, click Run a new test to run another test. You will need to run your next API call after this option is clicked.
Click Save.
JSONPath Syntax
The table below gives some of the basics of JSONPath Syntax. Note that these are not established by Qualtrics, but are standards used with JSON.
Attention: Setting up a JSON Event requires advanced programming knowledge. Although our support team is happy to help with the basics of putting information into the event, we cannot provide support on the programming aspects. You can always try asking our community of dedicated users instead.
| JSONPath | Description | Example |
|---|---|---|
| $ | The root object/element | $.stores[0].name |
| @ | The current object/element | $.stores[?(@.name===”ACME Store”)] |
| . | Child operator | $.eventDescription |
| .. | Recursive descendant operator | $.stores[0]..price |
| * | Wildcard | $.stores[*].name |
| [] | Subscript operator | $.stores[0].name |
| [,] | Union operator | $.stores[0,1] |
| [start:end:step] | Array slice operator | $.stores[0:10:2] |
| ?() | Applies a filter | $.stores[?(@.name==”ACME Store”)] |
| () | Script expression | $.stores[(@.length-1)] |
JSONPath Syntax Example
In this example, we will show you how, given a JSON object, the JSONPath table can be used.
This is our JSON object:
{
"eventDescription": "Monthly Revenue",
"stores": [
{
"name": "Acme Store",
"total": 1000000,
"topItem":
{ "price": "50", "description": "Anvil" }
},
{
"name": "The Banana Stand",
"total": 250000,
"topItem":
{ "price": "4", "description": "The Gob" }
},
{
"name": "Pizza Planet",
"total": 80000,
"topItem":
{ "price": "15", "description": "Pepperoni" }
}
]
}
Now, we should add the return values we see in the JSONPath table to make it more clear.
$ -> Acme Store
@ -> [
{
"name": "Acme Store",
"total": 1000000,
"topItem":
{ "price": "50", "description": "Anvil" }
}
]
. -> Monthly Revenue
.. -> 50
-> ["Acme Store", "The Banana Stand", "Pizza Planet"]
[] -> Acme Store
[,] -> [
Unknown macro: { "name"}
,
Unknown macro: { "name"}
]
**Change [start:end:step]'s Example to be "$.stores[1:3:1]"
[start:end:step] -> [
{
"name": "The Banana Stand",
"total": 250000,
"topItem":
{ "price": "4", "description": "The Gob" }
},
{
"name": "Pizza Planet",
"total": 80000,
"topItem":
{ "price": "15", "description": "Pepperoni" }
}
]
?() -> [{
"name": "Acme Store",
"total": 1000000,
"topItem":
{ "price": "50", "description": "Anvil" }
}]
() -> [
{
"name": "Pizza Planet",
"total": 80000,
"topItem":
{ "price": "15", "description": "Pepperoni" }
}
] Example API in Node Javascript
The example below is a basic template you can follow when formatting your Event Data.
Attention: Setting up a JSON Event requires advanced programming knowledge. Although our support team is happy to help with the basics of putting information into the event, we cannot provide support on the programming aspects. You can always try asking our community of dedicated users instead.
var request = require('request-promise');
var surveyId = "SV_XXXXXXXXXXXX";
var triggerId = "OC_XXXXXXXXX";
var brandId = "YOUR_BRAND_ID";
var userId = "UR_XXXXXXXXXXXXXXX";
var datacenter = "xx1";
var apiToken = "YOUR_QUALTRICS_API_TOKEN";
var url = "https://" + datacenter + ".qualtrics.com/inbound-event/v1/event/JSON/triggers" +
"?contextId=" + surveyId + "&userId=" + userId + "&brandId=" + brandId + "&triggerId=" + triggerId;
var payload = {
"text": "This is some text",
"object": {
"number": 4
},
"array": ["a", "b", "c", "d"]
};
var options = {
url: url,
json: true,
body: payload,
headers: {
"Content-Type": "application/json", // REQUIRED!!!
"X-API-TOKEN": apiToken
}
};
request.post(options).then(function (ret) {
console.log("success:", url, payload);
}).catch(function (err) {
console.log("error: ", url);
console.log(err);
}); Example: Integrating with Freshdesk
Qtip: This is separate from the Freshdesk task.
The JSON Event can be used to integrate with Freshdesk as a Webhook rule in the Dispatch’r. That means events in Freshdesk can then trigger tasks in Qualtrics, such as the creation of a ticket, or the distribution of a survey.
Qtip: Qualtrics Support can help you set up your JSON Event and connect it through Freshdesk. However, there might be some questions about Freshdesk functionality they cannot answer. If you have questions about the Freshdesk side, try checking out their documentation about Dispatch’r Rules.
In Qualtrics, set your Event to JSON Event.
Copy the URL.
In a new tab, log into Freshdesk.
In the Admin section, navigate to the option that best fits the kind of rule you want to set.
Qtip: Learn the difference between the Dispatch’r, Supervisor, and Observer on Freshdesk’s support documentation.
Create a new rule.
Set conditions to determine what Freshdesk event should trigger a task in Qualtrics.
Example: Maybe when a Freshdesk Agent makes it so the ticket’s status is changed from any status to Resolved, you’d like to send a CSAT survey using Qualtrics.
Add a new action and select Trigger Web Hook.
Set the Request Type to POST.
In Callback URL, paste the JSON Event URL from Step 2.
To use token authentication, add custom headers, enter X-API-TOKEN: and set it equal to your API token.
To use HTTP Basic authentication, click Requires Authentication, add your Qualtrics username, and then instead of your password, enter your API token.
Make sure the Encoding is JSON.
Manually select content to pass over, or choose Advanced to enter a JSON body.
Save your rule.
In Qualtrics, finish your workflow. In this example, we would probably add a Send survey via email or Send survey via text message (SMS) task.
Don’t forget to publish your survey changes when you’re ready to launch.
Qtip: For more on Freshdesk’s Webhooks, see the linked documentation on their support site.
Example: Integrating with ServiceNow
Qtip: This is separate from the ServiceNow Task.
The JSON Event can be used to integrate with ServiceNow. That means events in ServiceNow can then trigger tasks in Qualtrics, such as the creation of a ticket, or the distribution of a survey.
Qtip: Qualtrics Support can help you set up your JSON Event and connect it through ServiceNow. However, there might be some questions about ServiceNow functionality they cannot answer. If you have questions about how to log into and activate your ServiceNow developer instance, try checking out their documentation about Personal Developer Instances.
In Qualtrics, set your Event to JSON Event.
Copy the URL.
In a new tab, log into your ServiceNow developer instance.
Select REST Message.
Click New.
Name your rest message.
In the Endpoint field, paste the URL you copied in Step 2.
Change Authentication type to Basic.
Go to the HTTP Request tab.
Double click to add X-API-TOKEN.
In a new row, add the name Content-type.
Set the value to application/json.
Click Submit.
Reopen your Rest Message.
Under HTTP Methods, click New.
Give the method a name.
Set the HTTP Method to POST.
Set the Authentication type to Inherit from parent.
Click Submit.
Reopen the POST HTTP method you just created.
At the bottom of the page, select Preview Script Usage.
Copy the text.
Search and select Business Rules.
Select New.
Select a table.
Select Advanced.
Determine when the business rule is run.
Example: If you have selected Incident for your table, and want to send a CSAT survey for resolved tickets, you could add a condition stating this rule should run when Incident state changes to Resolved.
Qtip: Qualtrics Support can help you set up your JSON Event and connect it through ServiceNow. However, there might be some questions about ServiceNow functionality they cannot answer. If you have questions about how / when business rules run, please see ServiceNow’s documentation on how business rules work.
Go to the Advanced tab.
Paste the content you copied from Step 22 where it says Add your code here.
Add a body. This is where you communicate the information you’d like to pass over to Qualtrics.
Example: This is an example of the final code you would include in this field. Most of this code is the outbound message provided by ServiceNow and will vary from example to example. Unfortunately, Qualtrics Support cannot help you with any custom coding; if you have issues with your code, please reach out to ServiceNow’s community for assistance.
The bolded part of the code includes three additional functions not included in the original code: a JSON body that pulls the User ID and incident state, and a call that retrieves the email address of the incident customer so they can be sent the CSAT (italicized below). See ServiceNow’s documentation and consult their community if you have additional questions.
(function executeRule(current, previous /*null when async*/) {
// Add your code here
try {
var r = new sn_ws.RESTMessageV2('Qualtrics JSON Event ', 'JSON Event POST');
var body = {
"User ID": gs.getUserID()
"incident state": current.state.getDisplayValue()
};
var target = new GlideRecord('sys_user');
target.addQuery('sys_id', '=', current.caller_id);
target.query();
while(target.next()) {
body["email"] = target.email.getDisplayValue();
}
var response = r.execute();
var responseBody = response.getBody();
var httpStatus = response.getStatusCode();
gs.addInfoMessage(httpStatus);
}
catch(ex) {
var message = ex.message;
gs.addInfoMessage("Error communicating w Qualtrics " + message);
}
})(current, previous);
Add the body to the request. Add the following under the bolded, italicized portion of the code from the previous step:
r.setRequestBody(JSON.stringify(body)); Click Submit.
In Qualtrics, finish your workflow. To continue the CSAT survey example, we would probably add a Send survey via email or Send survey via text message (SMS) task.
Don’t forget to publish your survey changes when you’re ready to launch.
Example: Integrating with Microsoft Dynamics Through Microsoft Flow
Qtip: This is separate from the Microsoft Dynamics Task.
The JSON Event makes it so events in Microsoft Dynamics can then trigger tasks in Qualtrics, such as the creation of a ticket, or the distribution of a survey. For example, whenever you delete an account record in Microsoft, you can distribute a Qualtrics survey to the account owner that asks exit questions. (e.g., We’re sorry to see you go! How was your time with us? How can we improve?)
In order to integrate the JSON Event with actions that occur in Microsoft Dynamics, you actually need to do the set up inside Microsoft Flow instead of Dynamics. Don’t worry – Microsoft Flow comes free with every Microsoft Dynamics account, so you can log into Flow with your Dynamics information here.
Qtip: Qualtrics Support can help you set up your JSON Event and connect it through Microsoft Flow and Microsoft Dynamics. However, there might be some questions about Microsoft functionality they cannot answer. If you have questions about the Microsoft side, try checking out their documentation for Flow and their resources for Dynamics.
In Qualtrics, set your Event to JSON Event.
Copy the URL.
In a separate tab, go to https://us.flow.microsoft.com/en-us/ and use your Microsoft Dynamics information to log into Flow.
Select My Flows on the left.
Click New and select Automated – from blank.
Name the flow.
Select a trigger. This is the event that happens in Microsoft that will start the task in Qualtrics. You can choose whatever serves your purposes, but for this example, we would choose “When a record is deleted (Dynamics 365).”
Click Create.
Under Organization Name, log into your Dynamics account.
Under Entity Name, choose the type of record or file. For our example, we’d use “Accounts.”
Click Next Step, and select Add an Action.
Select HTTP.
Change the Method to POST.
Paste your JSON Event URL in the URI field.
Use token authentication. Under Headers, enter X-API-TOKEN and in the field next to it, paste your API token.
Under Body, you can enter a JSON body. This helps you decide the information you want to pass from Dynamics to Qualtrics.
Qtip: Use the Add dynamic content button to select Dynamics record fields you’d like to bring over to Qualtrics. Make sure you follow proper JSON format, as displayed in the screenshot. For help troubleshooting dynamic content, please reach out to Microsoft Support.
When you’re finished, click Save.
In Qualtrics, finish your workflow. In this example, we would probably add a Send survey via email or Send survey via text message (SMS) task.
Don’t forget to publish your survey changes when you’re ready to launch.
Qtip: Microsoft Flow is preferred for these steps because it is able to send more information to Qualtrics in the JSON Body. If you set this up inside Microsoft Dynamics instead of Flow, only fields changed during the Dynamics event will be sent to Qualtrics. For example, if you choose to trigger based on a record update, and only an “email” field is changed, the “name” and “address” won’t be sent to Qualtrics, even if you specifically ask for those fields in the body. Flow will send everything you asked for to Qualtrics, regardless of whether that field was changed in the triggering event.
Example: Integrating with Genesys PureCloud
Qtip: To set up this integration, you must have access to Genesys Cloud Architect and Genesys Web Service Data Actions.
Using JSON events, you can integrate with Genesys PureCloud to send customers a follow-up survey after completing a support phone or chat interaction.
For the workflow event, select the JSON event.
Click Copy URL to copy the event endpoint to your clipboard.
Without closing out of the JSON Event window, open a new tab in your browser and navigate to Genesys.
Navigate to Admin.
Click Actions.
Click Add Action.
Select Web Services Data Actions as the Integration Name.
Qtip: If you don’t have the option to select the Web Services Data Actions, then you need to enable the integration. See this page for more information.
Give your action an Action Name.
Click Add.
Navigate to the Setup tab.
Go to the Contracts tab.
Under Input Contract, select JSON.
Configure the properties that are sent to Qualtrics.
Example: For example, the below code will pass email address, phone number, first name, and last name.
{
"type": "object",
"properties": {
"emailAddress": {
"type": "string"
},
"phoneNumber": {
"type": "string"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
}
},
"additionalProperties": true
}
Go to the Configuration tab.
Change the Request type to POST.
In the Request URL Template field, paste the URL from the JSON Event in Qualtrics.
Click Add Header.
In the Key box, enter X-API-TOKEN.
In the Value box, enter your Qualtrics API token.
Go to the Test tab.
Enter test values for your properties.
Click Run Action.
Genesys will tell you if the action was successful. If it failed, the error response will be displayed to help you fix the issue.
Return to your JSON Event in Qualtrics and check that your properties were passed to Qualtrics successfully.
Click Save.
Click the plus sign ( + ) and then Task to set up the task you want to follow when the JSON event is triggered. In our case, we want to send a survey to respondents, so we select a Send survey via email or Send survey via text message (SMS) task.
Qtip: When setting up your task, use the piped text menu to use values passed from Genesys (e.g., customer email, name, etc).
After setting up the task in Qualtrics, return to Genesys and click Save & Publish.
Click Yes.
Navigate to Admin.
Click Architect.
Select Survey Invite in the flow dropdown menu.
Click Add.
Give your flow a Name, Description, and Division.
Click Create Flow.
Under the Data section in your Toolbox, select Call Data Action and drag it to the dropbox in the flow.
Give your action a Name.
For the Category, select Web Services Data Action.
For Data Action, select the data action you created earlier.
Next to each property, click the dropdown menu and select Expression.
For the property values, enter what data is being sent for each property. The box will autocomplete your fields as you type.
Qtip: This page has every default property included in the survey invite flow. You can also use complex expressions in situations where customer contact information is missing or requires additional formatting.
Qtip: Contact information is prefaced with Survey.CustomerContact.
Click the bottom-most box in your flow.
Select Toolbox, then Survey Invites, then Abort Survey.
Select optOut for the Disposition.
Click Publish. Genesys will validate the flow and then publish it. Once this is done, the flow is in place and will begin sending surveys to customers when they complete support interactions.
FAQs
Does the JSON event enable me to integrate with _?
Does the JSON event enable me to integrate with _?
In order to integrate via the JSON event, the third-party must satisfy the following requirements:
- Can be configured to make outbound HTTP POST calls (e.g. webhooks, custom application)
- Can authenticate by passing a header token
- Sets the Content-Type header to “application/json” and formats the request bodies as valid JSON (optional for Event Data)
How many events per minute can I make to my JSON event (op_start) before being throttled?
How many events per minute can I make to my JSON event (op_start) before being throttled?
The JSON event is subject to the standard Qualtrics API limits. If you start getting throttled, your server will receive an HTTP response code of 429.
How do I know if my JSON Event workflow fails?
How do I know if my JSON Event workflow fails?
If the workflow is enqueued, the op_start response will be 202 (Accepted). This provides no guarantee that the workflow will actually run and certainly does not communicate the result of running. You can also obtain workflow execution results via Workflows Reporting.
What are workflows? / Where are actions?
What are workflows? / Where are actions?
Actions have been renamed to workflows to better represent the product experience and to reflect how users engage with the product. See the Workflows Basic Overview page for more information about using workflows.
There are no changes to workflow functionality as part of this update.
There are no changes to workflow functionality as part of this update.
That's great! Thank you for your feedback!
Thank you for your feedback!