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 (use a tool like webhook.site for testing).
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).

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.

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.