Webhooks are a way of CIOPulse pushing survey data to one of your systems by calling one of your APIs, rather than one of your systems pulling data out by calling our Transactional Survey Responses API.
The Relationship Survey Webhook is automatically triggered when a customer completes a relationship survey. It POSTs the single survey response in JSON format to a URL of your choice in near-real-time. This is in contrast to the Relational Survey Responses API which you call to GET a list of matching surveys in JSON format.
Some ideas for what you could use the Relationship Survey Webhook for:
- Adding customer feedback to the corresponding project record in your project management system.
- Adding surveys to your reporting database in near-real-time.
- Integrating surveys with your workplace communication tool, such as Slack.
Turning on Webhooks
Webhooks are only available on our Corporate or Enterprise Plans. If you'd like to upgrade your plan so that you can use webhooks, please contact us at [email protected].
To turn on webhooks you will first need your own API - code that takes CIOPulse survey data and does something with it, e.g. adds the survey to your own reporting database. Your API has to be callable via a URL and able to accept the JSON payload that we POST.
Within the CIOPulse Portal, you can turn on relationship survey webhooks from the Integration section of your Preferences.
- RS Webhooks On? - Turn webhooks on or off for relationship surveys.
- RS Webhook URL - This is the URL that CIOPulse will call when a relationship survey has been completed.
- RS Webhook Username - If your API requires HTTP Basic Authentication, enter the required username here.
- RS Webhook Password - If your API requires HTTP Basic Authentication, enter the required password here. We store this encrypted.
Payload
When the webhook is triggered by a customer completing a survey, CIOPulse calls the Webhook URL and provides the survey data as a JSON payload.
The JSON payload looks like this:
{
"Webhook_ID": "617e67bd662e4",
"Response_ID":"453",
"Response_Datetime_UTC":"2021-10-12 02:12:09",
"Segment_Code":"NZ",
"Segment_Name":"New Zealand",
"Segment_2_Code":"SALES",
"Segment_2_Name":"Sales Team",
"Relationship_Survey_Code":"JAN21",
"Relationship_Survey_Name":"January 2021 Survey",
"Series_Code":"TEST",
"Series_Name":"Testing",
"Customer":"CUST123456",
"Rating":"8",
"Rating_Reason":"Support is good but slow",
"Suggested_Improvement":"More support staff!",
"Survey_Description":"English RS survey - DemoCorp",
"Survey_Language":"English"
}Webhook_ID is a unique ID for this trigger of the webhook. Response_ID is a unique ID for this survey.
Carriage returns (new lines) in the Comments field will appear in the JSON as \n. Quotes in these fields will be escaped and will appear as \".
If you use ServiceNow, your API may require the JSON above to be wrapped in additional JSON. If required, let us know and we can modify our webhook payload so that the JSON above is prefixed with:
{"sysparm_quantity":"1","variables":
and suffixed with:
}
Error Handling
When CIOPulse calls your API URL, it looks for an HTTP 200 response that indicates the call was successful. If your API returns any other HTTP return code, CIOPulse will interpret this as a failure.
CIOPulse will re-try a failed API call 4 times (5 times in total). The first call will be made within 5 minutes of the survey being submitted. The following four retries are made at increasing intervals, like so:
- Second attempt (first retry): 5 minutes after the first failed attempt.
- Third attempt (second retry): 10 minutes after the second failed attempt.
- Fourth attempt (third retry): 20 minutes after the third failed attempt.
- Fifth attempt (fourth retry): 40 minutes after the fourth failed attempt.
If the call was not successful after five attempts, it is marked as a failure and no further attempts are made.
You can force CIOPulse to make another attempt at any time, by clicking the 'Resend Webhook' button available when viewing an individual entry in the Webhook Log.
Viewing your Webhook Log
A log of webhook calls is available in the Main Menu of the Portal via the 'Webhook Log' function.
You can see a list of the most recent webhook calls.
- Listening Post - The type of survey the webhook was triggered for (Transactional or Relationship).
- Webhook ID - A unique identifier for this trigger of the webhook.
- Last Activity Date - The GMT timestamp of when we last tried to call your API.
- Last Response HTTP Code - The HTTP code your API returned when we last tried to call your API.
- Last Response - The first 100 characters of the response we received from the last API call.
- Number of Attempts - Shows you how many times we've called your API (0 to 5).
- Status - Will say"Succeeded" if we've received an HTTP 200 return code; "Failed" if we've called your API five times without receiving an HTTP 200 return code; "In Progress" if the API call has not yet Succeeded or Failed.
- Click on the Action icon (pencil) to see the JSON payload (survey details) and the response we received from the API call.
You can force the webhook to be retriggered by clicking the "Resend webhook" button.