Webhooks

Webhooks allow RewardOS to push updates to your system in real time. Strongly recommended for production-grade integrations.

Authentication

Each webhook request includes an X-Verify header containing an HMAC-SHA256 signature of the raw payload, encoded in Base64.

Signature Verification (Node.js)

import crypto from 'node:crypto';

function generateSignature(payload, secret) {
  return crypto.createHmac('sha256', secret).update(payload).digest('base64');
}

function verifyWebhook(rawBody, secret, headerSignature) {
  const expected = generateSignature(rawBody, secret);
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(headerSignature));
}

Always verify using the raw request body string before JSON parsing.

Egress IP Allowlisting (Optional)

You may allowlist RewardOS webhook egress IPs:

Environment	IPs
Staging	Provided during onboarding
Production	Provided during onboarding

Contact contact@rewardos.in for the current egress IP list.

Available Webhooks

Webhook	Triggers When
Brand Updated	Brand status, denomination, or amount restrictions change
Wallet Low Balance	Balance falls below your configured threshold
Order Reached Terminal State	A `PROCESSING` order becomes `SUCCESS` or `FAILED`
Brand Discount Update	Subvention/discount percentage changes for a brand

1. Brand Updated

{
  "id": "brand_id",
  "denominationType": "FIXED",
  "status": "ACTIVE",
  "denominations": [100, 1000, 5000],
  "amountRestrictions": {
    "minOrderAmount": 100,
    "maxOrderAmount": 5000,
    "minVoucherAmount": 100,
    "maxVoucherAmount": 5000
  }
}

Refresh your local catalog when you receive this event.

2. Wallet Low Balance

{
  "balance": 250.0,
  "threshold": 500.0
}

Top up before orders fail with E300.

3. Order Reached Terminal State

{
  "orderId": "01KRE64AH1YV85B97KZ4JWJGBC",
  "status": "SUCCESS"
}

On receipt, call GET /v1/partners/orders/:orderId to fetch full details including vouchers[].

4. Brand Discount Update

Notifies when discount / subvention percentages change for a brand. Update pricing displays accordingly.

Delivery Expectations

Respond with 2xx quickly; do heavy work asynchronously
Treat deliveries as at-least-once — dedupe by event / order id
RewardOS may retry on non-2xx or timeouts