NAV Navbar
Webhook

Webhooks

Introduction

Webhooks are notifications that are triggered automatically when a specific event occurs. Use Survicate Webhooks to send automatically triggered notifications whenever respondents interact with your surveys. When a new submission comes in, a notification that contains respondent's answer is immediately sent to your chosen destination: the endpoint URL you set.

Security

Listening to a webhook exposes the webhook endpoint to the web, allowing anyone to call it, and potentially giving opportunity for security breaches. That's why each webhook is secured with a verification token and signing secret. The above mentioned information are included in the header of the request, allowing you to verify that the webhook is sent by Survicate.

Verification token and signing secret can be found in Survicate integration settings panel. Each token can be regenerated in webhook settings.

Webhooks settings

Verification token

Each webhook includes a verification token in Token header. Token provides basic security by confirming that webhook comes from Survicate. Be noted that token is sent as plain text. This security method can be compromised i.e. by MITM attack.

Signing secret

Each webhook request is signed with signing secret. You can find webhook body signature in Hmac header that is generated by HMAC-SHA256 using signing secret. This is recommended security method.

Events

As a Survicate user you're able to choose which events will be triggered when receiving answers to your surveys.

Question answered

Sample payload

{
  "messageId": "c0101a21572ca643fd9f9ad40a5a4650",
  "deliveryTries": 0,
  "event": {
    "surveyCompleted": {
      "survey": {
        "id": "b92b6ecae6dd7207",
        "name": "Satisfaction"
      },
      "url": "https://survey.survicate.com/43f2d5789346d6ad",
      "timestamp": "2019-05-10T06:46:02+00:00",
      "respondent": {
        "id": "534759",
        "platform": "OSX",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.131 Safari/537.36",
        "attributes": []
      },
      "questionsAnswered": [
        {
          "choice": {
            "id": 21573,
            "body": "Great",
            "comment": null
          },
          "survey": {
            "id": "b92b6ecae6dd7207",
            "name": "Satisfaction"
          },
          "url": "https://survey.survicate.com/43f2d5789346d6ad",
          "timestamp": "2019-05-10T06:46:02+00:00",
          "respondent": {
            "id": "534759",
            "platform": "OSX",
            "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.131 Safari/537.36",
            "attributes": []
          },
          "question": {
            "id": 12123,
            "body": "How would you rate our customer service?"
          }
        },
        {
          "text": "Sample answer to your text question",
          "survey": {
            "id": "b92b6ecae6dd7207",
            "name": "Satisfaction"
          },
          "url": "https://survey.survicate.com/43f2d5789346d6ad",
          "timestamp": "2019-05-10T06:46:02+00:00",
          "respondent": {
            "id": "534759",
            "platform": "OSX",
            "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.131 Safari/537.36",
            "attributes": []
          },
          "question": {
            "id": 12122,
            "body": "What was the reason for your score?",
            "comment" : "Sample comment"
          }
        }
      ]
    }
  }
}

Question answered event is triggered upon each respondent's answer. Each answer to every single question will be sent along with respondent data.

Object Attribute Type Description
messageId string
deliveryTries number
questionAnswered type string Question type - described in detail below the table
questionAnswered timestamp string Timestamp of the event occurrence
questionAnswered url string URL where the response was given
survey id string Survey ID
survey name string Survey name
respondent attributes object All respondent custom attributes
question body string Question content
question id number Question ID
choice body string Answer content
choice comment string Respondent comment

Survey answered

Sample payload

{
  "messageId": "c0101a21572ca643fd9f9ad40a5a4650",
  "deliveryTries": 0,
  "event": {
    "surveyCompleted": {
      "survey": {
        "id": "b92b6ecae6dd7207",
        "name": "Satisfaction"
      },
      "url": "https://survey.survicate.com/43f2d5789346d6ad",
      "timestamp": "2019-05-10T06:46:02+00:00",
      "respondent": {
            "id": "534759",
            "platform": "OSX",
            "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.131 Safari/537.36",
            "attributes": []
          },
      "questionsAnswered": [
        {
          "choice": {
            "id": 21573,
            "body": "Great",
            "comment": null
          },
          "survey": {
            "id": "b92b6ecae6dd7207",
            "name": "Satisfaction"
          },
          "url": "https://survey.survicate.com/43f2d5789346d6ad",
          "timestamp": "2019-05-10T06:46:02+00:00",
          "respondent": {
            "id": "534759",
            "platform": "OSX",
            "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.131 Safari/537.36",
            "attributes": []
          },
          "question": {
            "id": 12123,
            "body": "How would you rate our customer service?"
          }
        },
        {
          "text": "Sample answer to your text question",
          "survey": {
            "id": "b92b6ecae6dd7207",
            "name": "Satisfaction"
          },
          "url": "https://survey.survicate.com/43f2d5789346d6ad",
          "timestamp": "2019-05-10T06:46:02+00:00",
          "respondent": {
            "id": "534759",
            "platform": "OSX",
            "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.131 Safari/537.36",
            "attributes": []
          },
          "question": {
            "id": 12122,
            "body": "What was the reason for your score?"
          }
        }
      ]
    }
  }
}

Survey answer event sends webhooks upon each survey completion. Please note that this event will be triggered only when the whole survey is completed.

Answer types

Survicate supports numerous question types.

Choice

"choice": {
        "id": 201139,
        "body": "Companies or organizations (B2B)",
        "comment": "mostly SMBs"
      }

For NPS

"choice": {
        "id": 9,
        "body": "promoter",
        "comment": null
      }

This is an answer that will be sent to following question types:

Attributes:

Attributes for NPS:

Fields

"fields": {
      "firstName":"Alan",
      "lastName":"Fresco",
      "email":"alan@example.com",
      "organization":"Example Corp",
      "department":"Product",
      "jobTitle":"Product Manager",
      "phone":"+48 123456789",
      "comment":"Comment",
      "addressOne":"Example Street",
      "addressTwo":"00000 City",
      "city":"Nashville",
      "state":"Tennessee",
      "annualRevenue":"0",
      "employees":"50",
      "industry":"IT"
    }

Fields are answers to contact form added to your survey.

fields attribute contains all answers collected through fields in contact form.

Choices

"choices": [
          {
            "id": 1021,
            "body": "IT/Product",
            "comment": "most important for our company"
          },
          {
            "id": 1022,
            "body": "Customer support",
            "comment": null
          },
          {
            "id": 1023,
            "body": "Marketing",
            "comment": null
          }
        ]

Choices are answers to multiple answer question - checkboxes.

Choices are presented as an array of responses. body contains answer presented as a string. comment is additional comment provided by respondent

Text

"text": "Awesome platform and great support!"

Question type: Text question

text contains answer presented as a string.

Date

"date": "2019-05-22"

Question type: Date

date contains answer presented as a string.

Support

👋 If you bump into any problems or need more support, just start a conversation using Intercom in the bottom-right corner and you will be immediately routed to our Customer Support Engineers.