Connect Braze Webhooks to RewardStar Cards

Who this is for: Marketing ops and Braze admins who want Braze to issue a RewardStar gift card when a campaign or Canvas step fires.
Time to complete: About 30–60 minutes (plus QA), once Incentable credentials and a RewardStar card template are ready.

Overview

When a Braze campaign or Canvas step runs, Braze sends an automated HTTP webhook to Incentable. Incentable issues a RewardStar gift card, emails the recipient the card (with a redeem link), and the recipient completes redemption in the RewardStar redeem flow.

If a recipient unsubscribes from the RewardStar email, they confirm on Incentable's unsubscribe page and Incentable then opts them out of email in Braze through the Braze REST API. This keeps Braze as the source of truth for email consent.

Optionally, in the same Braze multichannel campaign, you can also send a Braze push or email (for example, “Your gift card is on the way”) so the user hears from you in Braze as well as from Incentable/RewardStar.

Braze’s own docs describe a similar pattern: when a user hits a milestone or earns points, use webhooks plus your existing API to credit a reward to their account. See Create a webhook.

Prerequisites

Braze

Incentable / RewardStar

Get credentials from Incentable

1. Log in to the Incentable Admin Dashboard.
2. Select the program you want to issue RewardStar cards for (API keys are scoped to a single program).
3. Open Integrations and add a Braze integration (or open your existing one).
4. Under Permissions & Configuration → RewardStar, confirm Write is on. New Braze integration keys have it on by default. Read is optional, for looking up issued cards. Permission changes are made by Incentable — contact support if you need one changed.
5. Optionally set Default RewardStar Card on the same card so Braze payloads can omit cardId.
6. Save your Braze REST credentials (next section).
7. Generate the API key and store it in a secure password manager.

Save your Braze REST credentials

Incentable needs a Braze REST API key so it can opt recipients out of email in Braze when they unsubscribe.

1. In Braze, go to Settings → APIs and Identifiers and create a REST API key with only the email.status permission.
2. In Incentable, open the Braze integration and find the Braze REST API card.
3. Choose your REST cluster (for example AU-01 — rest.au-01.braze.com).
4. Paste the Braze API key and click Save Changes. Incentable stores it encrypted and shows only a masked prefix afterwards.

If the credentials are missing, card issue requests return 400 with code BRAZE_CREDENTIALS_REQUIRED.

Endpoint Braze should call

The URL is also shown on the Braze integration's settings page under Connection. See the RewardStar API reference for full field and response details.

Direction: Braze → Incentable (outbound webhook from Braze).

Headers

Request body for the Braze webhook composer

Fields

The body uses the same fields as the RewardStar API — see that page for every field, type and limit. The ones that matter most in Braze:

• member.email, member.firstname, member.lastname — required; map them from the Braze profile.
• denomination — required; must be a produced denomination on the RewardStar card.
• cardId — required unless a Default RewardStar Card is set on the integration.
• externalRef — strongly recommended; unique per cardId. Critical for Braze retries.

Recommended Braze → payload mapping

Fixed values vs Braze Liquid

Some fields can be hard-coded in the webhook body; others should almost always use Braze Liquid personalization.

Rule of thumb

• Profile fields (email, name, phone) → almost always Liquid.
• accountKey, denomination, and expiryDays → fixed or Liquid.
• Start with fixed values where possible. Use Liquid when the value must change per user or per event.

Choosing accountKey

Prefer, in order:

1. {{${user_id}}} — always present in Braze, stable, no custom attribute setup.
2. Custom attribute — when you already sync a CRM/external id into Braze and want Incentable to match on that same key.
3. Omit — Incentable matches/creates by email only (works, but weaker if emails change).

Simple (recommended for most campaigns) — Liquid for profile fields, Braze user id for accountKey, fixed amount and expiry:

{
  "member": {
    "email": "{{${email_address}}}",
    "firstname": "{{${first_name}}}",
    "lastname": "{{${last_name}}}",
    "accountKey": "{{${user_id}}}"
  },
  "denomination": 50,
  "expiryDays": 90,
  "cardId": "YOUR_REWARDSTAR_CARD_ID",
  "externalRef": "braze-{{campaign.${api_id}}}-{{${user_id}}}-{{event_properties.${reward_id}}}",
  "idempotencyKey": "braze-{{campaign.${api_id}}}-{{${user_id}}}-{{event_properties.${reward_id}}}"
}

Advanced — amount, expiry, and account key from Braze custom attributes / event properties. Adjust attribute names to match your workspace:

{
  "member": {
    "email": "{{${email_address}}}",
    "firstname": "{{${first_name}}}",
    "lastname": "{{${last_name}}}",
    "accountKey": "{{custom_attribute.${account_key}}}"
  },
  "denomination": {{event_properties.${gift_card_amount}}},
  "expiryDays": {{custom_attribute.${card_expiry_days}}},
  "cardId": "YOUR_REWARDSTAR_CARD_ID",
  "externalRef": "braze-{{campaign.${api_id}}}-{{${user_id}}}-{{event_properties.${reward_id}}}",
  "idempotencyKey": "braze-{{campaign.${api_id}}}-{{${user_id}}}-{{event_properties.${reward_id}}}"
}

Static JSON sample (for smoke tests)

{
  "member": {
    "email": "jane.doe@example.com",
    "firstname": "Jane",
    "lastname": "Doe",
    "accountKey": "CRM-100245",
    "mobile": "+61400000000"
  },
  "denomination": 50,
  "expiryDays": 90,
  "cardId": "YOUR_REWARDSTAR_CARD_ID",
  "externalRef": "braze-qa-2026-07-22-001",
  "idempotencyKey": "braze-qa-2026-07-22-001"
}

Liquid-templated JSON sample (paste into Braze)

Use the simple example above for most setups. Keep externalRef unique for every intended card. Switch to the advanced example only when denomination, expiry, or account key must vary per user or event.

Braze setup steps

Aligns with Braze’s Create a webhook flow. Exact UI labels can vary by Braze version.

1. Create a Webhook Campaign, or add a Webhook component in a Canvas.
2. Webhook URL: paste the Incentable issue endpoint from above (also on the Braze integration's Connection card).
3. HTTP method: POST.
4. Request headers:
   • Authorization: Bearer <YOUR_API_KEY>
   • Content-Type: application/json
   • Optional but recommended: Idempotency-Key with the same Liquid expression as externalRef.
5. Request body: choose JSON / raw body and paste the simple Liquid sample from Fixed values vs Braze Liquid (or the advanced sample if values must vary). Confirm personalization resolves from the user profile and/or trigger event properties.
6. Compose / personalization: preview with a test user so email, name, denomination, and externalRef look correct.
7. Delivery / trigger:
   • Campaign: action-based on a custom event (example: reward earned, points threshold reached), or
   • Canvas: place the webhook step after the qualification path.
8. Optional multichannel: add a Braze email or push in the same campaign/Canvas to tell the user their gift card is on the way (Incentable still sends the RewardStar card email with the redeem link).
9. Save, run a test send, then launch.

Official Braze guide: Create a webhook

How Braze retries interact with RewardStar responses

Braze retries only for certain HTTP responses (for example 408, 429, 5XX). Most other responses — including 401 Unauthorized and other 4XX — are not retried. Retry-After and X-Rate-Limit-* only affect backoff when the response is already retry-eligible; they do not create retries for non-retriable errors.

Full Braze table: Response codes and retry logic.

Success response

A successful issue returns 201 with the card id, amount, expiry, test flag and redeemUrl. A replay of the same idempotency key returns 200 with the original payload. Field-by-field details are on the RewardStar API page.

Braze does not need to store anything from the response. Incentable emails the card and redeem link to the recipient.

Opted-out recipients

If the member has previously unsubscribed from Incentable emails, Incentable does not issue the card. Instead it holds the request in quarantine and returns 202 Accepted with "quarantined": true and a quarantineId. Nothing is drawn from the fund.

Program admins are notified and can review quarantined requests on the RewardStar card's Issue Cards page, then either Release & issue (for example, if the recipient has asked to receive it) or Discard. Resending the same externalRef while a request is in quarantine returns the same 202 rather than creating a second request.

Idempotency & duplicates

Because Braze may retry on 408 / 429 / 5XX, design every webhook body so a retry cannot mint a second card.

Troubleshooting

Start in Braze Message Activity / webhook error logs for the campaign or Canvas step, then map the HTTP status. The RewardStar API page lists every error code.

Test plan

1. Prefer a RewardStar card in test mode so QA does not draw down the fund.
2. In Braze, send a test webhook to a known inbox with a unique externalRef (for example braze-qa-<date>-001).
3. Confirm:
   • Braze shows a successful webhook delivery (201).
   • Recipient receives the Incentable/RewardStar email.
   • Card appears issued in Incentable (and isTest: true if using test mode).
4. Replay / retry simulation: send again with the same externalRef and same idempotency key.
   • Expect either 200 (idempotent replay) or 409 (duplicate externalRef) — both mean no second card was created. Confirm only one card exists.
5. Intentionally send with a bad API key.
   • Expect 401.
   • Confirm Braze does not keep retrying that failure (per Braze 4XX rules).
6. Optional: trigger a real Canvas/campaign path with a QA user before go-live.

Pre-launch checklist

• Braze package includes Webhooks (confirmed with Braze AM/CSM if needed)
• Webhook Campaign or Canvas webhook step created
• Trigger / Canvas path matches the intended reward moment
• Incentable Braze integration created; RewardStar Write enabled
• Braze REST cluster and email.status API key saved on the integration
• API key stored securely; used only in Authorization header (not in the URL)
• RewardStar card template active; denominations produced; branding complete
• Program fund funded or test mode used for QA then switched for production
• Default RewardStar card set or cardId included in the Braze body
• Liquid maps email, first name, last name, denomination correctly
• Stable unique externalRef (and matching idempotencyKey / Idempotency-Key) on every send
• Test send: 201, email received, one card issued
• Same-key resend: 200 or 409, still only one card
• Bad-auth test: 401, no Braze retry loop
• unsubscribeUrl removed from older webhook bodies (optional — it is ignored)
• Optional Braze email/push copy reviewed for the multichannel campaign
• Owners know where to check Braze Message Activity and Incentable Integrations activity

Related

• RewardStar Card (Admin) — set up the card template before Braze issues against it
• RewardStar API — full issue/lookup reference
• Connect Braze Webhooks to Prize Draws — enter members into a prize draw from the same Braze integration
• API Overview — base URL, auth, getting your API key
• Braze — Create a webhook
• Braze — Response codes and retry logic