Articles in this section

Setting Up Webhooks

Avatar
Molly
  • Updated
Follow

This article explains how to configure Webhooks in Brilliant Assessments to receive real-time notifications when responses are created, started, changed, or completed.

Webhooks let Brilliant Assessments notify your external systems automatically when something happens, such as when a respondent starts or completes an assessment. When an event occurs, BA sends the ResponseID to a URL you specify. You then call the API to retrieve the full response data. This is faster than polling because you receive instant notification instead of checking on an interval.

Tip: If you are using Zapier, the Brilliant Assessments V2 integration creates webhooks automatically. You do not need to follow the manual setup steps below. See Connecting Webhooks to Zapier instead.

On this page

Prerequisites

  • A paid Brilliant Assessments subscription (webhooks are not available during the free trial)
  • API V2 keys configured (see Using the API)
  • A receiving endpoint (your own server, Zapier, Make, or any service that can receive HTTP POST requests)

Enabling Webhooks

Webhooks must be enabled in your site's feature settings before they can be configured.

  1. Go to Administer > Site Settings
  2. Click the Integrations tab
  3. Select the API & Webhooks sub-tab
  4. Check the Use Webhooks checkbox

Once enabled, the webhook configuration area will appear below.

Creating a Webhook

  1. In Site Settings > Integrations > API & Webhooks, scroll to the Webhooks section
  2. Click Add Webhook

  3. Configure the webhook:

    Field Description
    1 - Assessment Select the assessment this webhook applies to, or select ALL ASSESSMENTS to fire for any assessment that has an External ID configured
    2 - Webhook URL The URL that will receive the webhook data (e.g., your server endpoint or Zapier Catch Hook URL)
    3 - Event Type When the webhook should fire (see Event Types below)
    4 - Organizations Optional. Only select if you want to create a webhook for a specific organization. See Partner/Organization Webhooks below
  4. Click Save

Note: 

  • You can configure multiple webhooks for the same assessment with different event types, or point multiple assessments to the same webhook URL.

  • The webhook URL contains an encrypted key which provides security for webhook deliveries. Keep your webhook URLs confidential.

Zapier users: If you are connecting to Zapier using the native Brilliant Assessments V2 integration, you do not need to manually create webhooks here. The webhook is automatically created in BA when you publish your Zap. You only need to visit this page to generate your API keys. See Connecting Webhooks to Zapier for the step-by-step guide.

Event Types

Event When It Fires Payload
response.created A new response is created (respondent record inserted) ResponseID only
response.started A respondent saves their first page or clicks Save Progress (the assumption is that they will have entered their name and email at this point) ResponseID only
response.changed A respondent completes the assessment for a second or subsequent time (hits Finish on the last page again) ResponseID only
response.completed A respondent completes the assessment ResponseID only

Tip: All webhook events return the ResponseID only. To retrieve the full response data (answers, scores, ratings, report details), call the Get Response API endpoint with the ResponseID. Use response.completed for most integration workflows (e.g., syncing results to a CRM, sending notifications, updating spreadsheets).

Webhook Payload

When a webhook fires, BA sends an HTTP POST request to your configured URL containing the event type, a timestamp, and the ResponseID for the affected response. The payload does not include full response data or personally identifiable information (PII).

{
    "EventType": "response.completed",
    "Timestamp": 1773859449,
    "Data": {
      "ResponseId": 1112057
    }
}

To retrieve the full response data (answers, scores, ratings, report details), call the Get Response API endpoint with the ResponseID:

GET /api/v2/responses/{responseID}

See Using the API for full endpoint documentation.

Testing Webhooks

After creating a webhook, you can send a test payload to verify your receiving endpoint is working correctly.

  1. In Site Settings > Integrations > API & Webhooks, find your webhook in the list
  2. Click the Test button next to the webhook
  3. BA will send a test payload containing a ResponseID to the configured URL
  4. Check your receiving endpoint (or Zapier) to confirm the data arrived

Note: If your webhook was automatically created by the Zapier integration, use Zapier's built-in test functionality instead of the Test button in BA. The Zapier integration includes its own test mechanism that pulls a real sample record from your assessment data.

Webhook Log

The webhook log shows a history of webhook deliveries, including successes and failures.

  1. In Site Settings > Integrations > API & Webhooks, find your webhook
  2. Click Show Delivery Log to expand the delivery log

The log shows:

  • Timestamp of each delivery (displayed in your site's configured timezone)
  • Response ID that triggered the webhook
  • Delivery status (success or failed)
  • Error details for failed deliveries

Note: The log can be toggled on and off. For high-volume assessments, keeping the log collapsed improves performance. There is currently no automatic retention period for log entries.

Partner/Organization Webhooks

Webhooks are configured at the assessment level in Site Settings > Integrations > API & Webhooks. Only administrators can create, edit, or delete webhooks.

Since webhooks only return ResponseIDs (no PII or full response data), no additional security configuration is needed for partner/organization setups. When a partner calls the API using their own organization API keys to retrieve the full response data, they will only see data associated with their own organization.

  • Webhook configuration is copied when an assessment is copied.

Troubleshooting

Use the questions below to troubleshoot common webhook issues.

+ Why isn't my webhook firing?

Check that the Use Webhooks checkbox is enabled in Site Settings > Integrations > API & Webhooks. Also verify that the assessment has an External ID configured if you selected "ALL ASSESSMENTS".

+ My webhook shows "Failed" in the log. What should I check?

The receiving URL may be unreachable or returned an error. Verify that the URL is correct, your endpoint is running, and it returns a 200 status code. Check the error details in the webhook log for more information.

+ I'm receiving duplicate webhook deliveries. Why?

Check your webhook list for multiple configurations for the same assessment and event type. Each matching webhook will fire independently.

+ The webhook payload only contains a ResponseID. Where is the full data?

This is by design. Webhooks intentionally return only the ResponseID to avoid transmitting sensitive data. To retrieve the full response data (answers, scores, ratings, report details), call the Get Response API endpoint with the ResponseID: GET /api/v2/responses/{responseID}

+ Webhook delivery seems delayed. Why?

Ensure your receiving endpoint responds within a reasonable timeout. Slow endpoints can cause delivery delays or timeouts that show as failures in the log.

Related articles

Comments

0 comments

Please sign in to leave a comment.