API Keys vs Webhooks

Overview

Brij provides two distinct integration methods for connecting your systems with the Brij platform: API Keys and Webhooks. While both enable data exchange, they serve fundamentally different purposes and operate in opposite directions.

API Keys

What Are API Keys?

A Brij API Key is a secure credential that allows external applications, tools, and services to interact with Brij's API endpoints programmatically. API Keys are used for system-to-system communication where your application needs to request data from Brij on demand.

Common tools that use API Keys include Postman (for API testing), backend services and data pipelines, analytics platforms such as Snowflake or BigQuery, and custom integration scripts.

Creating an API Key

To create an API Key, navigate to Settings → API Keys in your Brij dashboard, then click Create New API Key. Provide a descriptive key name (e.g., "Snowflake Reporting" or "Manufacturer Serial Numbers") and select the appropriate scopes for that key's intended use.

Available Scopes

Each API Key must be assigned one or more scopes at creation time. Scopes enforce the principle of least privilege — a key can only access what it was explicitly granted.

💡 Tip:  A reporting integration should only need Read access. An internal sync system that creates or updates records will require Write access. Never grant broader permissions than a key needs.

Webhooks

What Are Webhooks?

A Brij Webhook is an event-driven notification system. Rather than your application polling Brij for new data, Brij automatically pushes a payload to your specified endpoint the moment a qualifying event occurs on the platform.

Think of it this way: API Keys are pull — you go get the data when you need it. Webhooks are push — Brij sends the data to you the instant something happens. If you need real-time awareness of customer activity, registration updates, or rebate lifecycle changes, Webhooks are the right tool.

Setting Up a Webhook Automation

Webhooks in Brij are configured through the Automations flow. The setup consists of five steps:

1. Integration — Name your automation and select Webhook as the integration type.
2. Authentication — Select webhook URL as the authentication method and set the authentication type (e.g., external). Paste your webhook endpoint URL.
3. Action — Choose Brij → Webhook Integration as the action and select the payload version (currently V1).
4. Filters — Optionally scope the automation to specific experiences or leave set to All Experiences.
5. Triggers & Properties — Select which events trigger the webhook and expand each to configure which data properties are included in the payload.
6. Configuration — Set the HMAC Signing Key, Connector Type, External URL, optional HTTP headers, optional body overrides, and choose whether to Pause Automation on Failure. Click Save & Activate.

Supported Webhook Events

The following events can be configured as webhook triggers. Each event carries a standard set of contextual data groups — see the Payload Data Reference section for full field details.

Webhook Security — HMAC Signing

All webhook payloads sent by Brij are signed using an HMAC key. This allows your receiving endpoint to verify that the payload was genuinely sent by Brij and has not been tampered with in transit.

You may provide your own HMAC Signing Key during the Configuration step, or leave the field blank to have Brij auto-generate one. Store this key securely in your receiving system and use it to validate the signature header on every incoming request.

Reliability Setting

The Pause Automation on Failure option in the Configuration step controls how Brij handles delivery failures. When enabled, the automation is automatically paused if repeated delivery attempts fail, preventing silent data loss. It is strongly recommended to enable this setting in production automations so that failures surface visibly for investigation.

Payload Data Reference

Every webhook payload is composed of modular data groups. The groups included in each event are determined by the event type and the properties you enable in the Triggers & Properties step. Below is a reference of all available data groups and their fields.

General Event Data

Included in: Registration events, Form Submission, Review Submission, Rebate events.

• Event Timestamp — date — Timestamp of when the event occurred (ISO 8601).
• Custom Data — string — Arbitrary key-value pairs configured on the experience.

Device Data

Included in: Registration events, Form Submission, Review Submission.

• Device Name — string — e.g., Apple iPhone
• Device Type — string — e.g., Mobile
• Device Browser — string — e.g., Mobile Safari 17.4.1
• Device Language — string — e.g., en-US
• Device OS — string — e.g., iOS 17.4.1
• Device Screen Resolution — string — e.g., 1920x1080

Location Data

Included in: Registration events, Form Submission, Review Submission.

• Location City, State, Country, Zip — string
• Location Latitude / Longitude — number
• Location Type — enum — IP | GPS | Unknown

Experience Data

Included in: All events (except SMS Opt In/Out).

• Experience Type — enum — WebApp Product | WebApp Variant | Rebate | Digital Hub | Dynamic Link
• Experience Name, Title, Subtitle, Description — string
• Experience URL — string — e.g., https://brij.it/c/RUTY
• Experience Brij ID — string — Short code identifier (e.g., RUTY)
• Experience Product / SKU Number — string
• Experience Serial Number, Lot Number — string
• Experience Product Price, Product Currency — string
• Experience Image — string — URL to the experience cover image

Customer Data

Included in: All events (except SMS Opt In/Out).

• Customer IP — string
• Customer Email, Phone Number — string
• Customer First Name, Last Name — string
• Customer Email Consent — boolean
• Customer SMS Single Consent, SMS Double Consent — boolean
• Customer Address (full and line-by-line) — string

Registration Data

Included in: Registration events, Form Submission, Review Submission.

• Registration ID — string
• Registration Date — date
• Registration Method — enum — email | phone
• Registration Warranty Duration — string
• Registration Expiry Date — date
• Registration Status — enum — pending | active
• Registration Module Name — string
• Registration Discount Code / Discount URL — string
• Registration Purchase Date — date
• Registration Purchase Quantity — number
• Registration Purchase Channel — string
• Registration Purchase Receipt — [string] — array of receipt image URLs
• Registration Serial Number, Note — string

Admin Data

Included in: Registration Approval, Registration Denial events only.

• Admin Approval Type — enum — Manual | Automatic
• Admin Approver — string — e.g., support@brij.it

Form Data

Included in: Brij Form Submission event only.

• Form Module Name — string — Name of the form module (e.g., Survey)
• Form Data — object — Key-value pairs of the submitted form fields

Review Data

Included in: Brij Review Submission event only.

• Review Module Name — string
• Review Title, Text — string
• Review Rating — number — e.g., 5
• Review Display Name — string — e.g., John S
• Review Upload — string — URL to uploaded review media
• Review Form Data — object

SMS Opt In/Out Data

Included in: SMS Opt In Event, SMS Opt Out Event only.

• User Phone Number — string
• Campaign Phone Number — string
• Timestamp — string — ISO 8601 timestamp of the opt-in or opt-out action

Rebate Data

Included in: All Rebate events.

• Rebate ID — string
• Rebate Status — enum — Initiated | In Review | Approved | Paid
• Rebate Receipt — string — URL to submitted receipt
• Rebate Sign Up Method — enum — Phone Number Entry | Keyword
• Rebate Amount — string
• Rebate Approval Status — enum — Approved | Denied | N/A
• Rebate Approval Method — enum — Manual | Automatic
• Rebate Reviewer — enum — Internal | Brij AI
• Rebate Transaction ID — string

Rebate Campaign Data

Included in: All Rebate events.

• Rebate Campaign Name — string
• Rebate Campaign Start / End Date — string (ISO 8601)
• Rebate Campaign Grace Period — string — e.g., 3 days
• Rebate Campaign Terms — string
• Rebate Campaign Quantity Required / Quantity Back — number
• Rebate Campaign Cashback / Max Rebate Amount — string
• Rebate Campaign Status — enum — Active | Inactive

Choosing the Right Tool

Use API Keys when you need to query or export data on demand — for example, building a dashboard, generating a report, or syncing customer data into an external CRM on a scheduled basis. The data flow is initiated by your system.

Use Webhooks when you need your system to react in real time to events that happen within Brij — for example, triggering a fulfillment action when a rebate is approved, or logging a registration to your data warehouse the instant it is submitted. The data flow is initiated by Brij.

In many production integrations, both tools are used together: Webhooks handle real-time event streaming while API Keys handle historical data pulls and administrative operations.