Webhooks

Webhooks allow users to receive real-time notifications about key program events (like new applicants, task submissions, transactions, and more). When an event occurs, BrandChamp sends a secure POST request to your configured webhook endpoint. This enables seamless integrations with tools like CRMs, or internal automation workflows.

Why Use Webhook?

Here are some key use cases and reasons this feature matters:

• Automate Workflows Across Tools

  • CRM Syncing: Automatically push applicant or BrandChamp data into your CRM (like Salesforce or HubSpot) as soon as events happen.
• Save Time with Real-Time Updates
  • No more polling APIs or manual data exports; get event-driven updates the moment something changes in your BrandChamp program.
• Trigger Custom Notifications
  • Use webhook data to send branded email or SMS notifications via services like SendGrid, Twilio, or your internal comms stack.
• Enhance Reporting & Attribution
  • Log webhook events to your internal analytics or reporting tools for visibility into activity timelines, ambassador behavior, and program performance.
• Ensure Operational Reliability
  • Webhook retries and delivery tracking help ensure you don’t miss important events, like reward redemptions or task approvals; even if your endpoint temporarily fails.

How to Set Up a Webhook

1. Navigate to Settings → Integrations.
2. Look for Developer card & click on Edit
3. You'll land on the Webhook page; click Add Webhook button in the top right to create a new webhook
4. Enter the Name of this Webhook
5. Enter your Webhook Endpoint URL.
6. Select the events you want to subscribe to:
   • Applicant Applied
   • BrandChamp Added, Updated, or Removed
   • Task Submitted or Task Status Updated
   • Transaction Recorded
7. Click Save.
8. A Webhook Signing Secret will be generated; keep this safe! It’s used to validate payloads.

How to Test Your Webhook

• After saving, a “Test This Event” button becomes available in the UI.
• Choose an event type and click to simulate it.
• The test payload is sent to your endpoint, but note: Test events do not appear in the Webhook Events table.

To view real webhook activity:

• Trigger real events (e.g., submit a task, apply to a program).
• See processed events under Webhook Events

Payload Structure

Each webhook contains:

Header:

• X-Webhook-Signature-SHA256  : used for signature verification (Base64-encoded)

Body (JSON):

{
  "_eventId": "abc123",
  "_eventName": "task-submitted",
  "_eventOccurredAt": "2025-06-10T12:00:00Z",
  "_eventSentAt": "2025-06-10T12:00:01Z",
  "data": {
    "userId": "XYZ",
    "email": "user@example.com",
    ...
  }
}

• Fields starting with _  are system metadata.
• data  contains event-specific info (e.g., task title, transaction value, tags added).

Field Definitions

All timestamps are in ISO 8601 format (UTC).

Signature Verification

To ensure authenticity:

1. Compute a HMAC-SHA256 hash of the raw payload body using your Webhook’s Signing Secret.
2. Encode the result in Base64.
3. Match it against the value in X-Webhook-Signature-SHA256  .

This step prevents spoofing and ensures the payload was genuinely sent by BrandChamp.

Retry Behavior

If your server responds with an error (non-2XX):

• The event will be retried up to 16 times over 48 hours.
• Retries use exponential backoff.

Ensure your endpoint is highly available and responds quickly with a 200 OK  if successful.

Event-Specific Payload Reference

The structure of the data  object depends on the event type.

Below are the supported events and what they include.

1. applicant-applied

Triggered when someone submits an application form.

Key Fields in data

• userId -  BrandChamp user ID
• firstName , lastName - Applicant name
• email - Applicant email
• tags - Tags assigned at time of application
• applicationForm - Information about the form used
• answers - All responses submitted in the application form

2. brandchamp-added

Triggered when an applicant is approved and added to the program.

Additional Fields

• _reason - Why the user was added (e.g. applicant-approved )
• notes - Admin notes
• registered - Indicates whether the user completed registration
• applicationForm - Application metadata
• answers - Application responses (if applicable)

3. brandchamp-updated

Triggered when a BrandChamp profile is updated.

Key Fields

• userId , firstName , lastName , email
• notes
• tags
• registered

The _updated  Object

This object shows exactly what changed in the update.

Example:

"_updated": {
  "firstName": false,
  "lastName": false,
  "email": false,
  "tags": true,
  "notes": true,
  "registered": false,
  "tagsAdded": ["new-tag1"],
  "tagsRemoved": ["tag1"]
}

Explanation:

• Boolean values (true  / false ) indicate which fields were modified.
• tagsAdded  lists new tags applied.
• tagsRemoved  lists tags that were removed.

This allows your system to react only to specific changes if needed.

4. brandchamp-removed

Triggered when a BrandChamp is removed from the program.

Includes:

• userId
• firstName , lastName
• email
• notes
• tags

5. task-submitted

Triggered when a BrandChamp submits a task for review.

Key Fields

• submittedAt - Timestamp of submission
• title - Task title
• completionFormat - Format of submission (e.g., text, URL)
• currentStatus - Current task review status
• activity - Parent activity details
• user - BrandChamp who submitted the task

6. task-status-updated

Triggered when a task status changes (approved, rejected, undone, etc.).

Key Fields

• submittedAt
• reviewedAt
• title
• currentStatus
• previousStatus
• activity
• user
• reward  (if applicable)

The reward  object may include:

• type - e.g. points
• value - reward amount

7. transaction-recorded

Triggered whenever a points or monetary transaction occurs.

Key Fields

• valueType - points  or monetary

  value - Transaction amount

  • Positive = credit
  • Negative = debit
• affectsLifetimeCredit - Whether it impacts lifetime totals
• createdAt - When the transaction was recorded
• description - Transaction description
• user  – BrandChamp details
• balance  – Updated balance after this transaction

Balance Object

"balance": {
  "points": 100,
  "pointsLifetimeCredit": 100
}

This reflects the user’s updated totals after the transaction.

These were all supported events and what they include.

Best Practices

• ✅ Always verify the webhook signature.
• ✅ Log payloads for debugging and audit trails.
• ✅ Return a 2XX   status to avoid retry floods.
• ✅ Use secure HTTPS endpoints.
• ❌ Don’t share your signing secret publicly or with third parties.

Managing Webhooks

• Edit or Delete webhooks anytime via the Webhooks page.
• You can add multiple subscriptions for different endpoints.

FAQs

Q: Can I use this with Zapier Or Make?

Yes! As long as they support incoming webhooks, you can use the event payloads to automate workflows. However, we have a native integration with Zapier. Read more about zapier integration here.

Q: Can I preview payloads?

Yes - use the “Event Payload Samples” tab to see example payloads for each event type.

Q: Will test events show up in Webhook Events?

No. Only real events are shown in the table.