Integrating your system with Segmanta using Webhooks

Learn more about Webhooks and how to use them with our informative integration guide.

Webhooks are one way that SaaS applications send automated messages or information to other applications/systems.

Webhooks are a powerful feature that allow you to receive real-time "push-notification" style messages to your web services.

What are Webhooks?

Traditionally there are two ways of receiving information from external systems; either via polling or webhooks. Polling is not covered in this guide, but you can think of polling as your system "asking" Segmanta for new information, and receiving all information that has changed since the last poll. Using polling means that your system must consult the Segmanta system frequently, on a timed basis, and ask for new information. 

Webhooks are automated messages which are sent from our system when something happens; specifically when a question is answered or when a survey is completed.

Webhooks are delivered to unique URLs, which are made available by your system, and are configured inside of Segmanta. When something changes in your survey with a webhook notification configured, the Segmanta system will attempt to send a request with a JSON (Javascript Object Notation) payload in the body, and several headers.


Note: Traditionally, Webhooks can send either JSON or XML Payloads. In general, XML is seen as too heavy for modern system-to-system payloads, and so Segmanta supports only JSON payloads.

Webhooks are Similar to APIs but are generally simpler. Whereas an API would give access to any of the system functionalities available, which may not be required, webhooks focus on sending you only the information that your application asked for.

Flow Overview

- Configure the survey webhooks to send all answers as they are given (upon question answered).

- Segmanta sends each answer to your webhook endpoint with the answer data that has changed/been given, with supporting metadata to allow you to correlate this webhook request.

- Your system processes the webhook, saves the data that it requires, and then responds with either a successful HTTP response code (200) or in the case of an error and you'd like to retry later, an error HTTP response code (4xx/5xx).

Example

Survey: Customer Satisfaction Survey

System: CRM

Required behaviour: "For each completed answer of the customer satisfaction survey, attach responses to the customers CRM record).

Setting up Segmanta Webhooks

Testing webhooks with RequestBin and/or Postman

The easiest way to get started is to use a public RequestBin (or similar service) which will receive your test webhooks whilst you are exploring whether Webhooks are right for you. 

Generally, for Webhooks, there are many public services that are free and are great tools for testing Webhooks:

  1. RequestBin (https://requestbin.com - operated by Pipedream)
  2. Any other tool that accepts HTTP requests in, on SSL, for POST requests.

RequestBin

RequestBin provides a service to create a temporary webhooks URL and send data to it to see how it is structured. Note: RequestBin is a public service owned and operated by Pipedream - we cannot provide support for their services to test webhooks.

Steps to use: 

  1. Create an account at https://requestbin.com/
  2. Click "Create a RequestBin"; it will then display you a webhook URL which you should copy
  3. Go to the Survey that you would like the webhooks to be sent from on the Segmanta platform, and navigate to Configure > Webhooks.
  4. Click "Add Hook"
  5. Name your webhook with something memorable which will help you distinguish configurations
  6. Paste the URL copied from step 2 into the "Where to send the data field"?
  7. Select from the options, "On Survey Completion" or "On Question Completion"
  8. Set the webhook to "Active"
  9. Open your Production Survey URL (Survey previews do not trigger webhooks as data is not persisted for Survey Sessions), and if your answer to step 7 was "On Survey Competition", complete the survey, or if "On Question Completion", answer a question
  10. Open the RequestBin page again, and you will see webhooks sent by Segmanta for those survey responses.

Note: Webhook delivery is usually instant, but may take up to 5 seconds to be delivered. In the case your system is unable to handle a webhook at this time, we retry periodically to try and deliver your system the data.

Additional Technical Reading