Webhooks

Webhooks enable you to respond to events that take place in your ShopSurvey account programmatically and collect survey data in real-time.

Webhooks require knowledge of coding or how to use a workflow automation tool that supports incoming webhooks. We recommend working with a developer to use webhooks.

Webhooks can be created in the dashboard under API Keys & Webhooks > Webhooks or through the REST API.

Create Webhooks from the Dashboard or REST API

Creating a Webhook

To create new Webhooks, you'll need three pieces of information:

• Topic - The unique identifier for the event you want to listen to, e.g. Response.Created or Session.Abandoned, etc. You can see the entire list of Webhook Events and what their payloads look like below.

• HTTP Method - The HTTP Method your Webhook endpoint is expecting. Valid values are GET and POST.

• URL - The URL to make the request against each time this Webhook is run.

Once you've registered your Webhook, it will start receiving traffic immediately (upon those events taking place). If you'd like to test your integration, just click the "Send Test Message" option on the Webhook dropdown menu:

Sending Test Messages to your Webhook Endpoint

Available Topics

Here is a list of each Webhook Topic and what the corresponding payload structure looks like.

Survey.Created

This event is called each time a new Survey is published to your account. Here is an example payload for the Survey.Created event:

{
  "survey": {
    "id": "f8015fcb-1b27-4c4e-ac5b-b5766b6548ad",
    "name": "string",
    "headline": "string",
    "subheadline": "string",
    "survey_url": "string",
    "reward_type": "none",
    "audience_type": "basic_url",
    "reward_discount_code": "string",
    "short_key": "string",
    "status": "open",
    "created_at": "2023-02-17T23:56:16Z",
    "updated_at": "2023-02-17T23:56:16Z",
    "published_at": "2023-02-17T23:56:16Z"
  }
}

Survey.Updated

This event is called each time changes are saved to a Survey in your account. Here is an exa

{
  "survey": {
    "id": "bbf50f93-2a6f-467d-ad92-110b55f2df6c",
    "name": "string",
    "headline": "string",
    "subheadline": "string",
    "survey_url": "string",
    "reward_type": "none",
    "audience_type": "basic_url",
    "reward_discount_code": "string",
    "short_key": "string",
    "status": "closed",
    "created_at": "2023-02-17T23:58:03Z",
    "updated_at": "2023-02-17T23:58:03Z",
    "published_at": "2023-02-17T23:58:03Z"
  }
}

Survey.Deleted

This event is called each time a Survey is deleted from your account. Here is an example payload for the Survey.Deleted event:

{
  "survey": {
    "id": "f8015fcb-1b27-4c4e-ac5b-b5766b6548ad",
    "name": "string",
    "headline": "string",
    "subheadline": "string",
    "survey_url": "string",
    "reward_type": "none",
    "audience_type": "basic_url",
    "reward_discount_code": "string",
    "short_key": "string",
    "status": "closed",
    "created_at": "2023-02-17T23:56:16Z",
    "updated_at": "2023-02-17T23:56:16Z",
    "published_at": "2023-02-17T23:56:16Z"
  }
}

Session.Created

This event is called each time a new Survey Session is started by one of your Respondents. Here is an example of the Session.Created event:

{
  "survey_session": {
    "id": "0ac407cc-2f49-4ebd-aafa-c0e435148ae9",
    "respondent_id": "317e43ff-c404-4b47-a491-85b9014ba7a3",
    "survey_id": "11ea858d-5958-4732-9cde-8bed191de15c",
    "status": "start",
    "variables": {
      "var1": "value1",
      "var2": "value2",
      "var3": "value3"
    },
    "created_at": "2023-02-18T00:00:26Z",
    "updated_at": "2023-02-18T00:00:26Z"
  }
}

Session.Abandoned

This event is called each time a Survey Session is abandoned by one of your Respondents. Here is an example of the Session.Abandoned event:

{
  "survey_session": {
    "id": "f15619c3-30bb-4d25-8de9-f052fc5ad4a5",
    "respondent_id": "fcbad21d-3200-4a95-9722-e2e77021790b",
    "survey_id": "bfb9ad8a-ddbf-4e86-a5c0-6607405eac7a",
    "status": "abandoned",
    "variables": {
      "var1": "value1",
      "var2": "value2",
      "var3": "value3"
    },
    "created_at": "2023-02-18T00:00:42Z",
    "updated_at": "2023-02-18T00:00:42Z"
  }
}

Session.Disqualified

This event is called each time a Survey Session is marked Disqualified. Here is an example of the Session.Disqualified event:

{
  "survey_session": {
    "id": "5729ab44-3c64-4930-b3d8-acef217a2206",
    "respondent_id": "9f57f9a6-b761-4c33-a193-a4f815559b0e",
    "survey_id": "11e804d5-09fc-4f0e-bda2-be6bc811c51c",
    "status": "disqualified",
    "variables": {
      "var1": "value1",
      "var2": "value2",
      "var3": "value3"
    },
    "created_at": "2023-02-18T00:01:04Z",
    "updated_at": "2023-02-18T00:01:04Z"
  }
}

Response.Created

This event is called each time a new Survey Response is collected from one of your Respondents. Here is an example payload for the Response.Created event:

{
  "session_id": "ffd1072f-6122-4e6d-a553-7c345e242a76",
  "survey_id": "d9aef04a-3927-498e-909c-6071610ae123",
  "respondent_id": "68e254d8-a593-40b4-947e-98e3072b58fe",
  "respondent_name": "John Appleseed",
  "respondent_email": "[e-mail]",
  "respondent_phone": "[phone]",
  "respondent_optin_status": "subscribed",
  "created_at": "2023-12-05T04:38:46.155Z",
  "question_bd4ab475ec8b": "Advertisements online, Word of Mouth",
  "question_78cd638eb211": "Entertainment, News",
  "question_4f7f7f3826a7": "A few times a week",
  "question_ff63564b98fe": "Yes",
  "question_553a5ef6a171": "18-24"
}

Respondent.Upserted

This event is called each time a Respondent record is created or updated. Either manually, through a data sync, or survey responses. Here is an example payload for the Respondent.Upserted event:

{
  "id": "5b9c425d-ff5c-41a1-81c0-c515ec08b859",
  "average_order_value": 75.0,
  "city": "Denver",
  "country": "US",
  "created_at": "2023-08-20T20:46:14.798Z",
  "email": "[e-mail]",
  "last_order_placed_at": "2023-08-20T20:46:14.798Z",
  "locale": "en",
  "name": "John Appleseed",
  "optin_status": "subscribed",
  "phone": "[phone]",
  "respondent_no": 4313,
  "shopify_url": null,
  "source": "shopify_customer",
  "state": "CO",
  "tags": [
    {
      "id": "f790316e-9d45-4f13-809a-3cd1ece4a738",
      "created_at": "2023-08-20T20:46:18.197Z",
      "tag": "Churned User",
      "updated_at": "2023-08-20T20:46:18.197Z"
    }
  ],
  "total_order_value": 750.0,
  "total_orders": 10,
  "updated_at": "2023-08-20T20:46:14.798Z",
  "website": null
}