Connect Braze Webhooks to Prize Draws

Who this is for: Marketing ops and Braze admins who want Braze to enter a customer into a prize draw when a campaign or Canvas step fires, for example after a purchase, a sign-up or a milestone.
Time to complete: About 30 minutes (plus QA), once an Incentable prize draw and a Braze integration are set up.

Overview

When a Braze campaign or Canvas step runs, Braze sends an HTTP webhook to Incentable. Incentable finds the member (or creates them as Pending), adds the entries to the prize draw, and records the request in your integration's Activity log. If the prize draw's Entry received email is turned on, Incentable emails the entrant to confirm.

The customer never fills in a form. Their Braze profile supplies their details, and your Braze trigger decides when they qualify.

Every entry goes through the same rules as an entry added in the Admin dashboard: the prize draw must be Active and inside its entry period, per-member and per-submission entry limits apply, and excluded members are rejected.

Prerequisites

Braze

Incentable

Get credentials from Incentable

1. Log in to the Incentable Admin Dashboard.
2. Select the program that runs the prize draw (API keys are scoped to a single program).
3. Open Integrations and add (or open) a Braze integration. A Custom API integration also works if you are calling from your own system rather than Braze.
4. Under Permissions & Configuration → Prize Draws, confirm Write is on. New Braze integration keys have it on by default.
5. Optionally choose a Default Prize Draw on the same card and save.
6. Generate the API key and store it in a secure password manager.

Find the prize draw ID

If you are not using a default prize draw, you need the prize draw's ID for the webhook body. In the Admin dashboard, open the prize draw, go to the Entries tab and click API. The Prize draw ID is shown with a copy button.

Endpoint Braze should call

The URL is also shown on the Braze integration's settings page under Connection.

Headers

Request body for the Braze webhook composer

Fields

The body uses the same fields as the Prize Draw Entries 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.
• prizeDrawId — required unless a Default Prize Draw is set on the integration.
• quantity — optional, 1–400 (default 1); prize draw entry limits also apply.
• externalRef — required for Braze (or idempotencyKey / an Idempotency-Key header); unique per prize draw.

Recommended Braze → payload mapping

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 id into Braze and want Incentable to match on the same key.
3. Omit — Incentable matches or creates by email only (works, but weaker if emails change).

Simple body (recommended for most campaigns)

One entry per qualifying event, fixed prize draw:

{
  "prizeDrawId": "YOUR_PRIZE_DRAW_ID",
  "member": {
    "email": "{{${email_address}}}",
    "firstname": "{{${first_name}}}",
    "lastname": "{{${last_name}}}",
    "accountKey": "{{${user_id}}}"
  },
  "quantity": 1,
  "externalRef": "braze-{{campaign.${api_id}}}-{{${user_id}}}-{{event_properties.${order_id}}}",
  "idempotencyKey": "braze-{{campaign.${api_id}}}-{{${user_id}}}-{{event_properties.${order_id}}}",
  "metadata": {
    "campaign": "{{campaign.${name}}}"
  }
}

Advanced body (entries vary per event)

Entries from an event property, for example one entry per $50 spent calculated in Braze. Adjust property names to match your workspace:

{
  "member": {
    "email": "{{${email_address}}}",
    "firstname": "{{${first_name}}}",
    "lastname": "{{${last_name}}}",
    "accountKey": "{{custom_attribute.${account_key}}}"
  },
  "quantity": "{{event_properties.${entries}}}",
  "externalRef": "braze-{{campaign.${api_id}}}-{{${user_id}}}-{{event_properties.${order_id}}}",
  "idempotencyKey": "braze-{{campaign.${api_id}}}-{{${user_id}}}-{{event_properties.${order_id}}}",
  "metadata": {
    "orderId": "{{event_properties.${order_id}}}",
    "store": "{{event_properties.${store}}}"
  }
}

This example omits prizeDrawId, so it uses the Default Prize Draw set on the integration.

Static JSON sample (for smoke tests)

{
  "prizeDrawId": "YOUR_PRIZE_DRAW_ID",
  "member": {
    "email": "jane.doe@example.com",
    "firstname": "Jane",
    "lastname": "Doe",
    "accountKey": "CRM-100245"
  },
  "quantity": 2,
  "externalRef": "braze-qa-2026-10-20-001",
  "idempotencyKey": "braze-qa-2026-10-20-001",
  "metadata": { "source": "qa" }
}

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 prize draw entry endpoint from above.
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 body (or the advanced body if entries vary).
6. Compose / personalization: preview with a test user so email, name, quantity and externalRef look correct.
7. Delivery / trigger:
   • Campaign: action-based on a custom event (for example, purchase completed), or
   • Canvas: place the webhook step after the qualification path.
8. Optional multichannel: add a Braze email or push in the same campaign/Canvas, for example "You're in the draw!". Turn off the prize draw's Entry received email in Incentable if you don't want the entrant to get two confirmations.
9. Save, run a test send, then launch.

How Braze retries interact with prize draw responses

Braze retries only for certain HTTP responses (for example 408, 429, 5XX). Most other responses, including 401 and other 4XX, are not retried. See Braze's Response codes and retry logic.

Success response

A successful request returns 201 with the submissionId, the number of entries added, the member's total entries and a test flag. A replay of the same idempotency key returns 200 with the original payload and adds nothing. Field-by-field details are on the Prize Draw Entries API page.

Idempotency & duplicates

Look up a submission (optional)

Braze does not need this, but it is useful for support and reconciliation. It requires Prize Draws: Read on the integration — see Look up a submission.

Troubleshooting

Start in Braze Message Activity / webhook error logs, then check the Incentable integration's Activity log. Every request, including rejected ones, is recorded there. The Prize Draw Entries API page lists every error code.

Test plan

1. Put the prize draw in Test mode and make sure it is Active and inside its entry period.
2. In Braze, send a test webhook for a QA user with a unique externalRef (for example braze-qa-<date>-001).
3. Confirm:
   • Braze shows a successful webhook delivery (201).
   • The entries appear on the prize draw's Entries tab with source API.
   • The request shows as allocated in the integration's Activity log.
   • The QA inbox receives the entry confirmation (if the Entry received email is on).
4. Retry simulation: send again with the same externalRef and idempotency key. Expect 200 or 409, and no new entries.
5. Send with a bad API key. Expect 401, and confirm Braze does not keep retrying.
6. Send once with externalRef removed. Expect 400 REFERENCE_REQUIRED and no entries.
7. Before launch, turn Test mode off on the prize draw. Test entries are not included in live draws.

Pre-launch checklist

• Braze package includes Webhooks
• Webhook Campaign or Canvas webhook step created
• Trigger / Canvas path matches the moment a customer should be entered
• Braze integration created in Incentable with Prize Draws: Write
• API key stored securely; used only in the Authorization header
• Prize draw Active, entry period covers the campaign, entry limits reviewed
• Default Prize Draw set or prizeDrawId included in the Braze body
• Liquid maps email, first name and last name correctly
• Stable unique externalRef (and matching idempotencyKey / Idempotency-Key) on every send
• Test send: 201, entries visible in Incentable, Activity log shows allocated
• Same-key resend: 200 or 409, no extra entries
• Bad-auth test: 401, no Braze retry loop
• Decided which confirmation the entrant gets: Incentable email, Braze message, or both
• Prize draw Test mode turned off for go-live

Related

• Connect Braze Webhooks to RewardStar — issue gift cards from the same Braze integration
• Prize Draw Entries API — the same endpoint from your own system via a Custom API integration
• API Overview — base URL, auth, getting your API key
• Braze — Create a webhook
• Braze — Response codes and retry logic