Receive survey data with Webhooks

Webhooks are a powerful tool to deeply integrate Refiner and leverage survey data in your backend systems. When activated, Refiner sends a request containing user data to a given endpoint whenever a certain trigger event occurs.

Setting up webhooks

Refiner allows you to create multiple webhooks, each with their own configuration. This allows you to send survey data to different endpoints simultaneously.

Start by navigating to the “Integrations > Webhooks” within your Refiner dashboard and click on “Create Webhook”.

You’ll be prompted to name your webhook, add a target URL and choose a trigger event.

In addition, you can also choose to include a secret token to validate and authorize incoming webhooks.

Webhook payload schema

Webhooks are sent as HTTP POST requests and their payload was designed to provide a comprehensive set of user data with each request.

User related metadata

All webhooks include the project Uuid (environment), the triggering event, generic user data such as their ID, email address, timestamps, and the segments they belong to.

Webhooks also include an “account” object. This object is only relevant if you are grouping your users when identifying them. If you don’t use the grouping feature, you can ignore the account object.

User traits

The “attribute” object contains all traits which we have on record for the given user. These traits include data that you provided when identifying the user, automatically generated data fields (e.g. timestamps, counts, ..), as well as all survey responses we’ve received for a user.

The survey response

If the trigger event is set to “Survey Interaction”, the webhook also includes data related to the triggering survey interaction. The “form” attribute describes the survey and the “response” attribute includes survey response data.

Sample payload

Below is an example of a typical webhook payload in Refiner.

{
    "uuid": "9205e5d0-f728-11ea-95d6-25411f8367ca",
    "project_uuid": "56421950-5d32-11ea-9bb4-9f1f1a987a49",
    "remote_id": "Your-User-ID",
    "email": "user@email.com",
    "first_seen_at": "2020-09-15T07:53:40.000000Z",
    "last_seen_at": "2020-09-15T07:53:48.000000Z",
    "attributes": {
        "did_you_hear_the_latest_news": "yes",
        "form_submissions_count": "1",
        "form_views_count": "1",
        "how_big_is_your_team": "10+",
        "plan": "enterprise",
    },
    "segments": [
        {
            "uuid": "56466b00-5d32-11ea-ac9b-ed991110cd88",
            "name": "All Users"
        },
        {
            "uuid": "63a027f0-9af2-11ea-b3cb-559f22ac4088",
            "name": "Active Users"
        },
        {
            "uuid": "001368e0-9f60-11ea-b34a-d43258357a51",
            "name": "Promoters"
        },
        {
            "uuid": "0611f7b0-9f60-11ea-9826-e14c34c4cf0",
            "name": "Power Users"
        }
    ],
    "account": {
        "uuid": "9206a9a0-f728-11ea-b411-7921dfc65301",
        "remote_id": null,
        "domain": null,
        "first_seen_at": "2020-09-15T07:53:40.000000Z",
        "last_seen_at": "2020-09-15T07:53:48.000000Z",
        "attributes": {
          
        }
    },
    "triggered_event": "Saw Survey",
    "form": {
      "uuid": "34780fd0-2c11-11ec-8f58-7bd83b655011",
      "name": "NPS Survey"
    },
    "response": {
      "uuid": "18de5430-c64c-11ec-aa71-e1784a46b058",
      "first_shown_at": "2022-04-27T17:04:27.000000Z",
      "last_shown_at": "2022-04-27T17:04:27.000000Z",
      "show_counter": null,
      "first_data_reception_at": null,
      "last_data_reception_at": null,
      "completed_at": null,
      "dismissed_at": null,
      "received_at": null,
      "data": {
        "nps": "9",
        "something": "else"
      },
      "tags": [
        {
          "uuid": "e48ba000-5543-11ec-a6ba-613839220c53",
          "name": "Tag#1"
        }
      ]
   }
}