Manage webhooks

Webhooks allow Bazaarvoice to send real-time event notifications to your server when specific actions occur. When a configured event triggers, Bazaarvoice sends an HTTPS POST request to the endpoint URL you specify.

This automated push mechanism eliminates the need for constant API polling, ensuring your system stays synchronized with user-generated content as it happens.

Important: The Webhooks feature is available only for Enterprise clients; contact Bazaarvoice Support to upgrade. 

Benefits of using Bazaarvoice webhooks

• Instant updates: Receive notifications immediately when specific review-related actions occur (e.g., a new review is submitted or approved).
• Reduced overhead: Save server resources by reacting to events rather than fetching data on a schedule.
• Seamless integration: Trigger downstream workflows, such as sending thank-you emails, updating internal dashboards, or alerting customer service teams to low ratings.

Read the following sections to learn how to manage and optimize your webhooks:

• How webhook works
• Required solutions and roles
• Create webhook
  • Why secret key is needed 
• Payload delivery
• Edit endpoint
• Archive endpoint
• Webhooks FAQs

How webhook works

1. Create a webhook: In the Bazaarvoice Portal, create a webhook by adding an endpoint URL and select the required event triggers to activate the endpoint.
2. Secret key: A secret key is generated for every webhook. Save it securely immediately, as it cannot be recovered and is required for your developers to authenticate Bazaarvoice event callbacks.
3. Event trigger: An action occurs within the Bazaarvoice platform (e.g., a new review is submitted or approved).
4. Payload delivery: Bazaarvoice packages the event data into a JSON payload.
5. POST request: Bazaarvoice sends this payload via HTTPS to your pre-configured destination URL.
6. Server acknowledgment: Your server receives the data and returns a 2XX OK status code to confirm successful receipt.
   
   

   Security tip: To ensure the integrity of the data, it is highly recommended to use a secure HTTPS endpoint and implement signature verification to confirm that the requests are authentically originating from Bazaarvoice.

Required solutions and roles

You must have the following solution and the following roles:

Note: To learn more about how solutions and roles are assigned in the Bazaarvoice Portal, refer to Users and permissions.

Create webhook

1. Sign in to the Bazaarvoice Portal.
2. Select the required client instance name from the Instance Selector drop-down list in the upper-right corner.
3. From the upper-right corner, select the settings icon .
4. Go to the Developer section and select Webhooks.
5. Select Add endpoint.
6. On the Add Endpoint page, enter the following details:
   1. Client Instance: Automatically populated based on your selection in the instance selector at the top right of the Portal (Step 2).
   2. Endpoint name: A name for the webhook used to identify and manage the endpoint in the Portal.
   3. Endpoint URL: The URL to which Bazaarvoice sends callback requests.
   4. Description (Optional): A brief description of the endpoint’s purpose for future reference.
   5. Select event triggers: The review event that triggers a callback. The Select Events page provides the necessary options to configure your preferred callbacks.
      
7. Select Add events and select the required event types for which you need payloads.
8. The "Secret key generated successfully" message is displayed. Please save this secret key securely—once lost, it cannot be recovered. Your developers need it to authenticate Bazaarvoice event callbacks.

Why secret key is needed

The secret key generated during endpoint creation serves two important purposes:

1. Decrypting the email address of the reviewer.
2. Verifying the authenticity of event callbacks sent to your callback URL.

Decrypt user email address

The UserEmailAddress is treated as Personally Identifiable Information (PII) and is encrypted using the unique webhook secret key generated during registration. To access this data, the client must decrypt the email address using that same secret key. For detailed instructions on how to decrypt PII, refer to the Bazaarvoice Developer Center.

Validate the authenticity of callbacks

When an event is triggered, Bazaarvoice sends the payload to your configured callback URL. Each request includes a custom header: X-BV-Signature

To validate the callbacks:

1. Take the raw request payload exactly as received.
2. Use the secret key provided at the time of endpoint creation.
3. Generate an HMAC using the SHA-256 algorithm. See the next section for algorithms in different languages.
4. Compare your generated signature with the value in the X-BV-Signature header.
   1. If they match, the request is valid.
   2. If they don’t, reject the request as it may not be from Bazaarvoice.

How to calculate HMAC

The algorithm to calculate the HMAC Sha256 signature using Kotlin is as follows:

import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
import aws.smithy.kotlin.runtime.content.BigInteger

fun calcHmacSha256(secretKey: String,payloadData: String): String {
try {
val mac = Mac.getInstance("HmacSHA256")
val secretKeySpec = SecretKeySpec(secretKey.toByteArray(Charsets.UTF_8),
"HmacSHA256")
mac.init(secretKeySpec)

5

Java

Python
val hmacSha256 = mac.doFinal(payloadData.toByteArray(Charsets.UTF_8))
return String.format("%064x", BigInteger(1, hmacSha256))
} catch (e: Exception) {
throw RuntimeException("Failed to calculate hmac-sha256", e)
}
}

The algorithm to calculate the HMAC Sha256 signature using JAVA is as follows:

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.math.BigInteger;
public static String calcHmacSha256(String secretKey, String data) {
  try {
    Mac mac = Mac.getInstance("HmacSHA256");
    SecretKeySpec secretKeySpec = new
      SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256");
    mac.init(secretKeySpec);
    byte[] hmacSha256 = mac.doFinal(data.getBytes("UTF-8"));
    return String.format("%064x", new BigInteger(1, hmacSha256));
  } catch (Exception e) {
    throw new RuntimeException("Failed to calculate hmac-sha256",
                               e);
  }
}

The algorithm to calculate the HMAC Sha256 signature using Python is as follows:

import hmac
import hashlib

def calc_hmac_sha256(secret_key, data):
  try:
    byte_key = secret_key.encode('utf-8')
    message = data.encode('utf-8')
    hmac_sha256 = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
    return hmac_sha256
  except Exception as e:
    raise RuntimeError("Failed to calculate hmac-sha256") from e
    

The algorithm to calculate the HMAC Sha256 signature using JavaScript is as follows:

const crypto = require('crypto');
function calcHmacSha256(secretKey, data) {
  try {
    const hmac = crypto.createHmac('sha256', secretKey);
    hmac.update(data);
    return hmac.digest('hex');
  }
  catch (e) {
    throw new Error('Failed to calculate hmac-sha256: ' + e.message);
  }
}

The algorithm to calculate the HMAC Sha256 signature using PHP is as follows:

function calcHmacSha256($secretKey, $data) {
  try {
    $hmacSha256 = hash_hmac('sha256', $data, $secretKey, true);
    return bin2hex($hmacSha256);
  } catch (Exception $e) {
    throw new RuntimeException("Failed to calculate hmac-sha256: " .
                               $e->getMessage(), 0, $e);
  }
}

Note: To verify the data, use the secret key (that was generated during the confguration) and the payload to generate a signature. If it matches the X-BV-Signature header, the callback is authentic.

Payload delivery

When an event occurs on the Bazaarvoice platform—such as a review submission, approval, rejection, or review request—Bazaarvoice packages the event data into a JSON payload and sends it over HTTPS to your configured endpoint.

The table below lists the supported event types:

Sample payloads

{
  "Metadata": {
    "eventId": "019fa324-3a6f-70e9-8324-6ba24e48df24",
    "eventType": "notifications.review-request.ready.v1",
    "subject": "review-request",
    "occurredAt": "2026-07-27T10:34:50.291992181Z"
  },
  "Data": {
    "client": "test-client",
    "siteId": "main_site",
    "locale": "en_US",
    "notificationId": "019fa324-3a6f-70e9-8324-6ba24e48df24",
    "userExternalId": "8f43c19b",
    "emailAddressHash": "9613679216cc734be1069cc09147aaa7dcd6c777341b6b5f54b4f14436b28a37",
    "campaignId": "BV_PIE",
    "sentAt": "2026-07-27T10:34:48.247374192Z",
    "submissionUrl": "https://bazaarvoice.com/r/RWZuBgZQmxSVCaBT?",
    "unsubscribeUrl": "https://bazaarvoice.com/r/hvSyMPP6hM5dDGQf?",
    "products": [
      {
        "id": "de800a",
        "name": "Product Name",
        "image": "http://image.sa.xc.com/lib/fe59157073630379711d/m/1/productimage.jpeg",
        "submissionUrl": "https://bazaarvoice.com/r/1R3xu5zwyYQV3d1N?"
      }
    ]
  }
}

{
  "CurrentState": {
    "ratingsOnly": false,
    "rating": 4.0,
    "title": "Sample Review Title",
    "sourceClient": "generic_retailer_client",
    "contentLocale": "en_US",
    "id": 999999999,
    "CID": "00000000-0000-0000-0000-000000000000",
    "reviewText": "This is a sample review text used for demonstration purposes only. It does not represent actual customer feedback.",
    "moderationStatus": "REJECTED",
    "submittedAt": "2025-10-21T20:15:02.000Z",
    "lastModeratedAt": "2025-10-21T21:45:33.000Z",
    "lastModifiedAt": "2025-10-21T21:45:33.000Z",
    "SubjectProduct": {
      "productId": "product::generic-product-id"
      
    },
    "Contributor": {
      "authorId": "user_author_sample_id_12345"
      
    }
    
  },
  "Metadata": {
    "eventId": "00000000-0000-0000-0000-000000000000",
    "eventType": "cgc.review.status.rejected.v1",
    "subject": "review",
    "occurredAt": "2025-10-21T21:46:14.843Z"
    
  }
}

{
  "CurrentState": {
    "channel": "bazaarvoice",
    "contentFor": "product",
    "id": "889209",
    "SubjectProduct": {
      "productId": "product::data-gen-p99ajxl8nk"
      
    },
    "rating": 5,
    "submittedAt": "2023-01-01T00:00:00.000Z",
    "moderationStatus": "APPROVED",
    "reviewText": "Really comfortable, would buy again.",
    "title": "Great product!",
    "Contributor": {
      "authorId": "data-gen-user-hc57lnle41rag7qg07e42o9sa",
      "userNickname": "user123"
      
    },
    "isSyndicated": true,
    "syndicationSource": {
      "clientId": "syndicated-source-client",
      "name": "ClientName",
      "clientLogo": "https://example.com/logos/client.png"
      
    },
    "photos": [
      {
        "photoId": "photo-001",
        "url": "https://example.com/photos/photo-001.jpg"
        
      }
      
    ],
    "clientResponses": [
      {
        "id": "response-001",
        "response": "Thank you for your feedback!",
        "submissionTime": "2023-01-03T00:00:00.000Z",
        "sourceClientName": "ClientName",
        "logoImageUrl": "https://example.com/logos/client.png"
        
      }
      
    ],
    "syndicationDelayDays": 2,
    "syndicatedAt": "2023-01-03T00:00:00.000Z",
    "identifierType": "GTIN",
    "identifierValue": "012345678905"
    
  },
  "Metadata": {
    "eventId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "eventType": "cgc.syndicated-review.added.v1",
    "subject": "review",
    "occurredAt": "2023-01-03T10:00:00.000Z"
    
  }
}

{
  "CurrentState": {
    "channel":"bazaarvoice",
    "contentFor":"product",
    "id":"889209",
    "SubjectProduct": {
      "productId":"product::p99ajxl8nk"
    },
    "moderationStatus":"REMOVED",
    "isSyndicated":true,
    "syndicationSource": {
      "clientId":"syndicated-source-client",
      "name":"ClientName"
    }
  },
  
  "Metadata": {
    "eventId":"d4e5f6a7-b8c9-0123-defg-456789012345",
    "eventType":"cgc.syndicated-review.removed.v1",
    "subject":"review",
    "occurredAt":"2023-01-05T14:00:00.000Z"
  }
}

Edit endpoint

Note: Only Account Administrators and Technical Administrators are allowed to edit an endpoint.

1. Scroll to the endpoint that you want to edit. Select the action button next to it and select Edit.
2. In the Edit Endpoint form, update the necessary information.
3. Select Update endpoint.

Archive endpoint

Note: Only Account Administrators and Technical Administrators are allowed to edit an endpoint.

1. Scroll to the endpoint that you want to edit. Select the action button next to it and select Archive.
2. In the modal that appears, select Archive.

Webhook FAQS