Skip to main content
Skip table of contents

Emplifi Ratings & Reviews Webhooks

Webhooks let you get data from Emplifi Ratings & Reviews when events happen. Webhooks are HTTP callbacks that send real-time data in JSON format. They replace once-daily feed processing with updates that are automatically triggered when content is added or changed. Webhooks can directly integrate with your product information management (PIM) software, ecommerce platforms, or help desk systems.

Webhooks vs. APIs

Why use a webhook when an API endpoint can provide the same data? An API does something when you ask it to. A webhook does something when an event happens. With API calls, you start the communication. With a webhook, Emplifi starts the communication. It's like the difference between checking your mailbox each day to see if you have received a package (API) versus getting an alert when a postal worker delivers a package (webhook).

Parts of a webhook implementation

  • Emplifi has developed webhooks for the "review" entity type.

  • An event type is a category of actions in the Emplifi system that generates data for an entity. An event is an action.

    Event example: A review is published.

  • A webhook URL (endpoint), is a client-provided, secure destination that accepts HTTP post requests. This is where a Emplifi webhook will send event information.

  • A subscription is the mechanism that associates Emplifi events with your webhook URL.

    You subscribe to events, and Emplifi sends data for that event type to the webhook URL as the events occur.

  • A webhook payload is a JSON blob delivered to the webhook URL.

Getting started with webhooks

  1. Decide your security and privacy strategies.

    Depending on your security strategy, you may need your Emplifi siteKey, authKey, and bearer token.

    See Security and privacy for supported options.

  2. Determine your webhook URL, where Emplifi should deliver the webhook payload.

  3. Work with Emplifi Support to define which events to include in your subscription.

  4. Set up your webhook URL (endpoint) to receive event notifications (JSON Messages) with your security strategy.

  5. Work with Emplifi Support to:

    • Configure a webhook subscription for your test site

    • Test and verify the endpoint using your test site

    • Configure a webhook subscription for your production site

    • Test and verify the endpoint in production

Security and privacy

Privacy

Emplifi can remove personally identifiable information (PII) before sending data to your webhook URL.

Available PII policies include:

  • ALLOW_ALL - all PII is included in webhook events

  • HIDE_EMAIL - email addresses are hidden in webhook events

  • HIDE_ALL - no PII is included in webhook events

Security

Emplifi provides multiple authentication methods to support your security strategy as you set up a webhook URL (endpoint) where you will receive event notifications.

Available authentication strategies include:

  • NONE - no authorization method included

  • HTTP BASIC - payload includes HTTP basic authorization header (you provide a user name and password that we'll use to access your URL)

  • REQUEST SIGNING - a webhook request includes a signature parameter to verify that the sender is Emplifi, by hashing expected values associated with the call. This strategy can be combined with any of the other strategies

  • BEARER - payload includes site-specific OAuth 2.0 Bearer token authorization header

Request Signing Hash

With the REQUEST SIGNING authentication method, the query string of a webhook request includes a ttsign parameter. This field's value is a URL-encoded HMAC SHA256 hash of a combination of information from the webhook body and your webhook signed with your authkey. You can compute this value yourself to verify the request's authenticity.

The pre-hashed string is an ampersand-separated string. It includes the following fields in the listed order:

  • Webhook endpoint URL - the full webhook URL (endpoint) you provided Emplifi

  • Review Title - the title of the review in the payload, found in the title field of the entity in the request payload

  • Review Text - the review text from the text field of the entity in the request payload

  • Rating - the value from the rating field of the entity in the request payload

  • Request Timestamp - the timestamp of the request, found in the webhookTimestamp field of the request payload

The example payload below, with a hypothetical webhook-receiving endpoint of https://www.example.com/turnto_webhooks, results in the pre-hashed string:

https://www.example.com/turnto_webhooks&An awesome jacket!&This jacket fits perfectly and looks absolutely amazing.&4&1581368301529

image-20240422-131851.png

To verify the request's authenticity:

  1. Hash the string with an HMAC SHA256 hash, using your Emplifi site's authkey as the private key.

  2. Base-64 encode the hash.

  3. Compare the result to the ttsign parameter.

Event types in Emplifi webhooks

Event Type

Triggered When

CREATE

A review has been submitted.

PUBLISH

A review has been approved for public display.

HIDE

A review has been hidden.

DELETE

A review has been deleted.

VOTES

The total number of upvotes or downvotes on a review has changed.

TAG

Tags on a review have changed.

CS_FLAG_ON

A review has been flagged for Customer Service action.

CS_FLAG_OFF

The CS Flag has been removed from a review.

RESPONSE

A review response has been published, hidden or deleted.

MEDIA_PUBLISH

A picture or video submitted with a review has been approved for public display.

MEDIA_HIDE

A picture or video submitted with a review has been hidden.

Webhook payload data fields

Name

Description

entity

The entity includes the review id, content, and details.

entityType

The type of content in the entity, e.g. 'review'.

eventType

The category of the event. (See Event types in Emplifi webhooks, above)

affectedKey

The affectedKey identifies the entity type that triggered the webhook. For the entity, the affectedKey is "top". For a nested entity, it is formatted <childType>_<childId> .

Example: If your subscription includes published response events, the affectedKey woud be response__12345.

siteKey

This is the site key from your site’s Emplifi configuration page.

siteDisplayName

This is the display name from your site's Emplifi configuration page.

webhookTimestamp

This is the time when the event was converted to a webhook call.

webhookRequestId

The webhookRequestId is made up of:

<eventId>__<webhookTimestamp>__<attemptNumber>

(Where the attempt number is 0 on the initial call, 1 on the first call, etc.)

webhookVersion

This shows the schema version of the JSON payload.

Example webhook payload

If you have a webhook endpoint with a different payload schema, contact Emplifi Support to discuss payload customization. Advanced customization may incur additional costs and an extended timeline for testing and deployment.

Webhook payload example code
CODE 
{
  "siteKey": "ZeaequNgafr9koRsite",
  "siteDisplayName": "All About Coats",
  "webhookVersion": "1.3.0",
  "webhookTimestamp": 1581368301529,
  "webhookRequestId": "6c1ef535-265c-434c-91ef-3ad072bacb00__1581368301529__0",
  "entityType": "review",
  "eventType": "PUBLISH",
  "affectedKey": "top",
  "entity": {
    "id": 1,
    "acceptedTermsAndConditions": true,
    "autoModerated": true,
    "catalogItems": [
      {
        "sku": "1234567",
        "title": "Fleece-lined Winter Jacket with Hood",
        "url": "www.sample.com/products?sku=1234567",
        "category": "Outerwear",
        "reviewCount": 1,
        "ratingCount": 1,
        "averageRating": 4.5,
        "ratingBreakdown": {
          "1": 0,
          "2": 0,
          "3": 0,
          "4": 3,
          "5": 3
        },
        "active": true,
        "attributes": [
          {
            "type": "Product group",
            "typeLabel": "Product group",
            "values": [
              {
                "value": "Jackets",
                "valueLabel": "Jackets"
              }
            ]
          },
          {
            "type": "Assortment type",
            "typeLabel": "Assortment type",
            "values": [
              {
                "value": "Clothing",
                "valueLabel": "Clothing"
              }
            ]
          },
          {
            "type": "Age group",
            "typeLabel": "Age group",
            "values": [
              {
                "value": "Adult",
                "valueLabel": "Adult"
              }
            ]
          }
        ]
      }
    ],
    "csFlag": false,
    "campaign": "SPRING2021",
    "dateCreated": "2018-08-30T08:51:08+00:00",
    "dimensions": [
      {
        "type": 1,
        "dimensionId": 1,
        "dimensionLabel": "Overall Quality",
        "id": 4,
        "code": "Q4",
        "label": null,
        "value": 4
      },
      {
        "type": 2,
        "dimensionId": 2,
        "dimensionLabel": "Fit",
        "id": 7,
        "code": "FIT2",
        "label": "perfect",
        "value": null
      },
      {
        "type": 3,
        "dimensionId": 3,
        "dimensionLabel": "Occasion",
        "id": 2,
        "code": "OCC2",
        "label": "Casual",
        "value": null
      },
      {
        "type": 4,
        "dimensionId": 4,
        "dimensionLabel": "Impression",
        "id": 9,
        "code": "IMP1",
        "label": "Stylish",
        "value": null
      },
      {
        "type": 4,
        "dimensionId": 4,
        "dimensionLabel": "Impression",
        "id": 11,
        "code": "IMP3",
        "label": "Modern",
        "value": null
      }
    ],
    "downVotes": 1,
    "inappropriateFlag": false,
    "incentiveType": "SWEEPSTAKES",
    "incentivized": true,
    "locale": "en_US",
    "media": {
      "photo": [
        {
          "id": 11,
          "type": "photo",
          "caption": "so cool!",
          "imageType": "jpeg",
          "width": 108,
          "height": 109,
          "locale": "en_US",
          "published": true,
          "dateCreated": "2018-08-30T16:15:44-04:00",
          "normalUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1_L1000.jpeg",
          "thumbnailUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1_PZ320.jpeg",
          "originalUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1.jpeg",
          "ipViolationFlag": false,
          "inappropriateFlag": false,
          "offensiveFlag": false,
          "spamFlag": false,
          "offTopicFlag": false,
          "tags": [
            "IVR",
            "CSA"
          ]
        }
      ],
      "video": [
        {
          "id": 12,
          "type": "video",
          "caption": "build customer community",
          "provider": "youtube",
          "providedLink": "https://www.youtube.com/watch?v=Vr_r2uBg56g",
          "thumbnailUrl": "https://i.ytimg.com/vi/Vr_r2uBg56g/hqdefault.jpg",
          "thumbnailWidth": 480,
          "thumbnailHeight": 360,
          "width": 480,
          "height": 270,
          "authorName": "TurnTo",
          "authorUrl": "https://www.youtube.com/user/TurnToNetworks",
          "providerId": "Vr_r2uBg56g",
          "html": "<iframe width=\"480\" height=\"270\" src=\"https://www.youtube.com/embed/Vr_r2uBg56g?feature=oembed&rel=0&showinfo=0\" frameborder=\"0\" allow=\"autoplay; encrypted-media\" allowfullscreen></iframe>",
          "s88thumbDims": {
            "width": 117,
            "height": 88,
            "scaledTo": "h",
            "targetLeft": -15,
            "targetTop": 0
          },
          "s64thumbDims": {
            "width": 85,
            "height": 64,
            "scaledTo": "h",
            "targetLeft": -11,
            "targetTop": 0
          },
          "locale": "en_US",
          "published": true,
          "dateCreated": "2018-08-30T16:15:44-04:00",
          "tags": [
            "SAM",
            "IVR"
          ]
        }
      ]
    },
    "orderId": "KP-12345",
    "published": true,
    "purchaseDate": "2018-08-19T11:20:17+00:00",
    "rating": 4,
    "responses": [
      {
        "text": "Thank you for your review.",
        "locale": "en_US",
        "user": {
          "nickName": "BennyB",
          "firstName": "Benjamin",
          "lastName": "Brown",
          "emailAddress": "bennyb@allaboutcoats.com",
          "externalId": "ABC123456",
          "city": "Austin",
          "state": "TX",
          "country": "US",
          "ageRange": 3,
          "badge": {
            "text": "AllAboutCoats",
            "imageUrl": "http://allaboutcoats.com"
          },
          "shopperProfiles": [
            {
              "id": 1,
              "code": "MED"
            }
          ]
        },
        "dateCreated": "2018-10-22T11:05:03+00:00"
      }
    ],
    "reviewedDate": "2018-10-22T11:07:45+00:00",
    "reviewedFlag": true,
    "syndication": {
      "sourceName": "Best Coats",
      "siteUrl": "http://bestcoats.com",
      "logoUrl": "http://bestcoats.com/icon"
    },
    "tags": [
      "CSR",
      "INA"
    ],
    "text": "This jacket fits perfectly and looks absolutely amazing.",
    "textLength": 56,
    "title": "An awesome jacket!",
    "upVotes": 3,
    "user": {
      "nickName": "AndyA",
      "firstName": "Andrew",
      "lastName": "Adams",
      "emailAddress": "aa.89812@mymail.com",
      "externalId": "DEF98765",
      "city": "Springfield",
      "state": "OH",
      "country": "US",
      "ageRange": 2,
      "badge": {
        "text": "staff",
        "imageUrl": "http://clothesandaccessories.com"
      },
      "shopperProfiles": [
        {
          "id": 3,
          "code": "TALL"
        }
      ]
    }
  }
}

Retry behavior

If a webhook fails, the failure is logged. The call will be retried twice: first after 5 seconds and again after 15 seconds.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close