Each survey campaign supports the webhook data export functionality. This means that you can configure a webhook export, and every time you will receive a new survey response in this campaign, the data will be sent through the webhook's request URL to an external system.

You can manage existing webhook exports or create new ones in the "Export" section within a campaign's edit mode.

Click on a webhook export to edit it, or you can click the "+ Create new webhook" button to create a new one.

Manage webhooks

Create a new outbound webhook export

The webhook builder consists of two parts: the trigger and the action. The trigger is the event that is fired in Retently, and the action is the data that is sent to your webhook URL.

When creating a new webhook export, you will have to choose an event (which is the trigger).

Retently supports the following events:

All events
New feedback (with or without comment)
New feedback (without comment)
New feedback (with comment)
Custom score range
Contact opted out
Survey bounced

After choosing an event, you might be asked to apply an additional filter if you need to narrow down the data sent to the webhook URL.

Once you've finished configuring the webhook export event, you can proceed with setting up the webhook request. There are a few fields you will need to adjust or review to make sure that they're configured correctly:

Endpoint URL: Add the webhook URL that will receive the data generated by the selected event.
Headers: If you need to pass headers with your request, you can add them in the "Headers" section. You can add multiple headers by clicking the "+ Add headers" button.
Request Body (JSON): This text field will include a default request object, that includes all the information that our system can send to the webhook link. But if needed, feel free to remove fields, add new ones, or even change the structure of the request. Check the next chapter for more details on how to customize the "Request body" field.
Merge fields: This is a list with all the Retently properties that you can add to the "Request body" field. For example, if you've previously removed some fields from the default request and now you need to add them back, then you can copy them from this menu.
Reset to default: When clicked, this option will dismiss only the changes that you've made to the "Request body" field and will revert it to the default form. Any other changes made in other fields (such as the request URL or headers) will not be reset.
Send test: It gives you the possibility to test the webhook connection by sending a sample request to the specified endpoint URL and sending the data configured in the "Request body" field. Please keep in mind that the sample request includes dummy values, such as "John Doe" and "john.d@acme.com".

After you've configured and tested your webhook, make sure to save it, and switch the webhook ON, otherwise, no data will be sent via the specified endpoint URL.

Edit or delete webhooks

To edit an existing webhook export, you can simply click on it, or click the edit icon.

And to delete a webhook export, you will need to click the delete icon.

The webhook "Request body" editor

The "Request body" input field includes a simple JSON object with a list of fields and values that will be sent to your webhook URL once an event is fired in Retently.

Each record in the list consists of key-value pairs. Take for example contact_email: '{{contact_email}}' where:

contact_email - is the key, and you can name it whatever you need it to be. For example, if your external system is expecting the contact's email address to come in the user_email field then feel free to name it like that, and your key-value pair in the "Request body" editor will look like this: user_email: '{{contact_email}}'.
'{{contact_email}}' - is the value, and it can be a Retently merge field wrapped in {{}} or it can be a hardcoded value (for example: source: "Retently").

When creating a new webhook export, it will include a default object in the "Request body" field:

{
  event: '{{event}}',
  trigger: '{{trigger}}',
  contact_id: '{{contact_id}}',
  contact_email: '{{contact_email}}',
  contact_first_name: '{{contact_first_name}}',
  contact_last_name: '{{contact_last_name}}',
  contact_company_name: '{{contact_company_name}}',
  contact_company_id: '{{contact_company_id}}',
  contact_job_title: '{{contact_job_title}}',
  contact_country: '{{contact_country}}',
  contact_state: '{{contact_state}}',
  contact_city: '{{contact_city}}',
  contact_tags: '{{contact_tags}}',
  survey_outbox_id: '{{survey_outbox_id}}',
  survey_campaign_id: '{{survey_campaign_id}}',
  survey_campaign_name: '{{survey_campaign_name}}',
  survey_campaign_channel: '{{survey_campaign_channel}}',
  survey_campaign_metric: '{{survey_campaign_metric}}',
  template_id: '{{template_id}}',
  response_id: '{{response_id}}',
  response_date: '{{response_date}}',
  response_rating_category: '{{response_rating_category}}',
  response_main_rating: '{{response_main_rating}}',
  response_main_open_ended: '{{response_main_open_ended}}',
  response_additional_questions: '{{response_additional_questions}}',
  response_has_consent: '{{response_has_consent}}',
  response_topics: '{{response_topics}}'
}

The default request will include every piece of information that Retently can send to the webhook URL and that's related to the selected event.

IMPORTANT: The default request will also list all contact properties (aside from the system properties) you might have created in Retently. They will be displayed at the end of the in the JSON object, and will be prefixed with "property.". Here's an example of a couple of properties from the default request:

{
  properties_agent_name: '{{properties.agent_name}}',
  properties_department: '{{properties.department}}'
}

Edit the request body

You can fully edit the default request body and shape it to your needs. Here are a few use cases that you can use as examples.

Remove fields

If you feel that the data included in the default request is redundant, then you can simply unnecessary fields. You can literally remove everything until you're left with an empty object, such as:

{
}

But most likely you'll need to send at least something, so here's an example of a simplified request:

{
  contact_email: '{{contact_email}}',
  response_main_rating: '{{response_main_rating}}',
  response_main_open_ended: '{{response_main_open_ended}}'
}

Add fields using the "Merge fields" menu

If you've previously removed a field that needs to be re-added to the request, or if you've created a new contact property in Retently and you'd like to send it to the webhook URL, then you will need to add the "key" to the request and assign a "value" to that key, and the value should be a Retently merge field.

To explain with an example, let's say that you've created a new contact property "subscription_name", and now you need to add that property to the request. First, you will need to add the "key" name of that property to the request:

{
  subscription_name:
}

Next, you need to add the value, and to identify the syntax name of the merge field that you will use as a value, start by clicking the "Merge fields" button.

In the opened "Merge fields" menu start typing the name of the property, and once you've found it, hover your mouse over the property name to uncover the "Copy" button and click on it.

Finally, paste the copied value into the "Request body" field.

Anonymize contact's information

Also, in case you'd rather hide the survey respondents' information altogether, then you can remove the fields that include their personal information and leave only their IDs instead.

{
  contact_id: '{{contact_id}}',
  response_date: '{{response_date}}',
  response_rating_category: '{{response_rating_category}}',
  response_main_rating: '{{response_main_rating}}',
  response_main_open_ended: '{{response_main_open_ended}}',
  response_additional_questions: '{{response_additional_questions}}'
}

Moreover, if you have their external ID attached as a Retently property, then you can add it to the request, and using this ID, you will be able to match the contact with their record in an external system.

{
  contact_id: '{{property.external_id}}',
  response_main_rating: '{{response_main_rating}}',
  response_main_open_ended: '{{response_main_open_ended}}',
}

Configure a custom structure to the request body

Finally, you can fully customize the structure of the request body. By default, the request represents a simple JSON with a single parent object, and all the data is listed in that single object.

However, if the external system that you're integrating with is expecting the data to be delivered with a specific structure, you can configure it in the "Request body" field.

Let's say that instead of having all the fields mixed together you'd like to group contact properties, survey information, and the response data, then your request can look like this:

{
  event: '{{event}}',
  trigger: '{{trigger}}',
  contact_data: {
    contact_id: '{{contact_id}}',
    contact_email: '{{contact_email}}',
    contact_first_name: '{{contact_first_name}}',
    contact_last_name: '{{contact_last_name}}',
    contact_company_name: '{{contact_company_name}}',
    contact_company_id: '{{contact_company_id}}',
    contact_job_title: '{{contact_job_title}}',
    contact_country: '{{contact_country}}',
    contact_state: '{{contact_state}}',
    contact_city: '{{contact_city}}',
    contact_tags: '{{contact_tags}}',
    contact_properties: {
      properties_agent_name: '{{properties.agent_name}}',  
      properties_department: '{{properties.department}}'
    }
  },
  survey_data: {
    survey_outbox_id: '{{survey_outbox_id}}',
    survey_campaign_id: '{{survey_campaign_id}}',
    survey_campaign_name: '{{survey_campaign_name}}',
    survey_campaign_channel: '{{survey_campaign_channel}}',
    survey_campaign_metric: '{{survey_campaign_metric}}',
    template_id: '{{template_id}}'
  },
  response_data: {
    response_id: '{{response_id}}',
    response_date: '{{response_date}}',
    response_rating_category: '{{response_rating_category}}',
    response_main_rating: '{{response_main_rating}}',
    response_main_open_ended: '{{response_main_open_ended}}',
    response_additional_questions: '{{response_additional_questions}}',
    response_has_consent: '{{response_has_consent}}',
    response_topics: '{{response_topics}}'
  }
}

Set up Slack notifications through webhooks

If you want to enrich your Slack notifications with some custom properties (which currently is not supported by the native integration) you can achieve that through Webhooks.

First, you will need to make sure that you have a webhook from Slack. Your first step, will be to create a Slack app. Now that the app has been created, go to its settings and generate a Webhook. You can read more about this process here.

Once you have the Webhook, just copy it and insert it in your newly created Webhook. Don't forget to also authorize it. Once you are done, it should look something like this:

Now, for your body, you will need to specify a few things, such as the channel it should go to and the name of the app. If you want, you can even use emojis, like in the example below on line 4.

{
  channel: '#nps-score_channel',
  username: 'Retently',
  icon_emoji: ':tada:',
  attachments: [
    {
      pretext: ':tada: There is a good satisfaction rate from {{contact_first_name}} {{contact_last_name}} from {{contact_company_name}} his score was {{response_main_rating}} this customer Account Manager is {{properties.am_email}}',
      color: '#00d015',
      fields: [
        {
          value: 'Customers comment: {{response_main_open_ended}}',
          short: false
        }
      ]
    }
  ]
}