Guides
HomeMarketingOther resources
  1. Integrations
  2. Data and infrastructure
  3. Omniconnect

Omniconnect setup

Integration

This guide walks you through connecting a third-party platform to Bloomreach using Omniconnect. The steps use Typeform as an example, but the process is the same for any platform that supports webhooks.

📘

Note

Different platforms use different names for webhooks. Your platform may call them API notifications, web service requests, or something similar.

Before you start

You'll need:

  • A Bloomreach project with integration access.
  • A third-party platform that supports outgoing webhooks.
  • Basic familiarity with JavaScript (for writing transformation functions).

Step 1: Create the integration

  1. In Bloomreach, go to Data & Assets > Integrations.
  2. Click + Add new integration.
  3. Search for Omniconnect and click + Add integration.
  4. Accept the terms and conditions (once per project) and click Add integration.
  5. Give your integration a name and click Save integration.
❗

Warning

Don't delete or rotate the API key group that Omniconnect creates automatically. Rotating or revoking keys assigned to Omniconnect will cause data loss.

Step 2: Connect your platform

  1. In your Omniconnect integration, copy the Omniconnect URL.

    Omniconnect URL displayed in the integration settings.

    Copy Omniconnect URL to use in your third-party platform's webhook settings.

  2. Go to your third-party platform's webhook settings.

    1. Typeform: Workspace > Connect > Webhooks > Add a webhook.

      Typeform webhook settings showing the Add a webhook option.

      Adding a webhook in Typeform's Connect settings.

  3. Paste the Omniconnect URL into the webhook URL field.

  4. Add a description to clarify what this webhook does.

  5. Save the webhook in your platform.

Step 3: Write your transformation function

The transformation function converts incoming webhook data into a format Bloomreach can process. You write it in JavaScript inside the Bloomreach integration settings.

The transformation tab showing raw input data and transformed output side by side.

The transformation tab shows raw input data and transformed output side by side.

View incoming data

Before writing your function, check what your platform actually sends:

  1. Go to your Omniconnect integration and click Transformation.
  2. Open the Incoming request dropdown and select the most recent request.
  3. Inspect the Input tab to see the raw payload from your platform.

Write and test the function

  1. Write JavaScript in the editor to transform the incoming payload.
  2. Click Test transformation to test your function against the sample data.
  3. Inspect the Output tab to verify the result looks correct.

Your transformation function varies based on your platform and use case. For a complete Typeform example, see Omniconnect use cases.

Request requirements

For Omniconnect to accept a request:

RequirementValue
Content typeapplication/json
MethodPOST
Payload formatJSON
Maximum request JSON depth20 (nested objects)
Maximum payload size1 MB (larger payloads are rejected)

Transformation function limits

Every accepted webhook runs your JavaScript transformation function in an isolated runtime. These limits are platform-enforced—you can't change them in the UI.

LimitValueIf exceeded
Execution time500 ms per request (wall-clock)The request is recorded as a failed transformation in the Log tab. No customer events or profile updates are applied.
Memory64 MB per executionThe request is recorded as a failed transformation in the Log tab. No customer events or profile updates are applied.
Output commandsUp to 50 Bloomreach commands per requestThe request is recorded as a failed transformation in the Log tab. No customer events or profile updates are applied.
Transformation function source size36 KB maximumYou can't save the integration until you reduce your function below 36 KB. When updating an existing integration, the last saved valid function remains active.

Step 4: Launch the integration

  1. Click Save changes when your transformation function is ready.
  2. Click Start to activate the integration.
  3. Go to Data & Assets > Customers to confirm that events from your platform are appearing and that customer profiles are updating correctly.

Set up notifications (recommended)

Turn on email alerts to be notified when your integration runs into issues.

To add notification recipients:

  1. Go to your Omniconnect integration.
  2. Click the three dots next to the Start button.
  3. Click Notifications.
  4. Enter the email addresses of anyone who should receive alerts. This could include your implementation partner, internal teams, or technical contacts.
  5. Click Save.
📘

Important

Email notifications must be enabled in your account settings for this to work. Go to Settings > Notification settings > Get notifications via email and turn them on first.

HTTP response codes

CodeMeaningWhat to do
200 OKRequest received and accepted by Omniconnect.No action needed.
404 Not FoundInvalid integration ID or incorrect URL.Check your Omniconnect URL. Contact Bloomreach Support if it persists.
405 Method Not AllowedNon-POST request received.Use POST.
413 Payload Too LargeRequest is too big. Allowed size is below 1,032,192 bytes.Ensure requests fit the size limit. For bulk imports, use Imports. Contact the team with a feature request.
429 Too Many RequestsRequest exceeded Omniconnect API rate limits. This is intended as a safety valve for extreme spike/abuse traffic. Requests weren't accepted.Investigate what caused the burst on the origin platform and retry. For bulk imports, use Imports. Contact the team with a feature request.
500 Internal Server ErrorProcessing error on Bloomreach's side.Contact Bloomreach Support with a sample request and headers.
504 Gateway TimeoutRequest took too long to process.Check your payload size (aim for under 500 KiB). Contact Bloomreach Support with a sample request.

Troubleshooting

Events aren't appearing in customer profiles

This can happen for two reasons:

  1. Customer ID mismatch: If the customer IDs in your transformation output don't match the hard customer IDs configured in the project, Bloomreach can't link the event to an existing profile. The transformation may succeed, and events may be accepted, but they won't appear on the expected customer profile.
  2. Deleted or rotated API key group: If the API key group was deleted or rotated, recreate the integration—there's no way to restore a deleted key group.
Errors appeared after a platform update

If your third-party platform changed its webhook payload structure, your transformation function may no longer work. Contact Bloomreach Support and ask them to check the Audit Log for your integration. Include sample requests, headers, and the error codes you're seeing.

Transformation failures in the Log tab (timeout or memory)

Your function exceeded the 500 ms or 64 MB limit, or returned more than 50 commands. Optimize the function and retest with Test transformation. See Transformation function limits above.

Integration shows as active but no events appear

Check the following in order:

  1. Confirm the source platform is sending requests to the correct Omniconnect URL.
  2. Check the Log tab for incoming requests and transformation results.
  3. Confirm your function returns the correct customer IDs—if they don't match the hard IDs configured in your project, events are accepted but won't appear on the expected profile.
  4. If the Log tab shows no incoming requests, the platform may not be sending webhooks. Test using the platform's built-in webhook test tool.

Updated 1 day ago

Did this page help you?

© Bloomreach, Inc. All rights reserved.