Direction matters
Use this guide when the platform calls your endpoint.
Outbound webhooks notify your system about tenant events. They are separate from requests you make to the API and from provider events received by the platform. The distinction determines which signing contract applies.
Rebate Card X calls your endpoint
Tenant events use the signing and retry contract documented on this page.
Providers call Rebate Card X
Approved program providers and commerce providers use separate provider-specific authentication.
Read the ingress OpenAPIWebhook endpoints are created from an authenticated merchant session by an owner, administrator or developer role after access review. They are not created with an rbx_ API key.
Endpoint setup
Register a public HTTPS receiver.
- 01
Choose a dedicated URL
Use a public
https://endpoint. Local, loopback and private-network targets are rejected. - 02
Select event types
Subscribe only to the tenant events your system owns. A wildcard subscription receives every tenant event and requires broader compatibility handling.
- 03
Store the signing secret once
The full secret is returned when the endpoint is created. Store it in a secret manager; later reads do not return it.
- 04
Preserve the raw request body
Signature verification must use the exact bytes received, before JSON parsing, reformatting or field normalization.
Redact authentication material and minimize retained payload data according to your approved integration purpose.
Event envelope
Identify the event before interpreting its payload.
The envelope tells your receiver which event occurred, which tenant it belongs to and how to recognize a duplicate. Interpret the event-specific payload only after verifying the delivery and checking that context.
Example eventJSON
{
"event_id": "01J64P4D6S8W2H7K5M9Q3T1VXC",
"event_type": "card.issued",
"occurred_at": "2026-08-24T15:18:42.000Z",
"tenant_id": "01J64M1H4EJ9B7K2D5P8S3V6XA",
"aggregate_id": "01J64P29N7R4C8B6X5D2H1Q9KT",
"version": 1,
"payload": {
"cardId": "01J64P29N7R4C8B6X5D2H1Q9KT",
"awardId": "01J64NZW3F6R8K4T2C7M5B9QXA"
}
}event_id- Semantic event identity. Use it as the primary deduplication key.
event_type- Names the lifecycle transition and selects the payload contract.
occurred_at- UTC time when the event occurred, not the time your endpoint received it.
tenant_id- The tenant boundary for the event. Verify that it matches the expected integration.
aggregate_id- The primary domain record associated with the event.
version- Positive event schema version.
payload- Event-specific data. Ignore unknown additive fields and reject data your integration is not approved to retain.
Signature verification
Authenticate the delivery before parsing it.
| Header | Value |
|---|---|
webhook-id | Delivery-record identifier used in the signed value. Retries retain this identifier; the separate attempt counter increases. |
webhook-timestamp | Unix epoch seconds used in the signed value. |
webhook-signature | v1,<unpadded-base64url-digest> |
The canonical value is webhook-id.webhook-timestamp.raw-body. Compute HMAC-SHA-256 with the endpoint signing secret, encode the digest as unpadded base64url, and compare in constant time.
Verification helperNode.js
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyRcxWebhook({ rawBody, headers, secret }) {
const deliveryId = headers.get("webhook-id");
const timestamp = headers.get("webhook-timestamp");
const signature = headers.get("webhook-signature");
if (!deliveryId || !timestamp || !signature) return false;
const [version, suppliedDigest] = signature.split(",", 2);
if (version !== "v1" || !suppliedDigest) return false;
const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!Number.isFinite(ageSeconds) || ageSeconds > 300) return false;
const canonical = deliveryId + "." + timestamp + "." + rawBody;
const expectedDigest = createHmac("sha256", secret)
.update(canonical, "utf8")
.digest("base64url");
const expected = Buffer.from(expectedDigest, "utf8");
const supplied = Buffer.from(suppliedDigest, "utf8");
return expected.length === supplied.length && timingSafeEqual(expected, supplied);
}The five-minute age check in the example is a consumer-side replay window. Apply it only after your clocks are synchronized, and retain event_id deduplication independently.
Delivery semantics
Acknowledge durable acceptance with any 2xx response.
- Success
- Any
2xxresponse marks the delivery successful and resets the endpoint's consecutive failure count. - Timeout
- The delivery request times out after 15 seconds.
- Redirects
- Redirect responses are not followed. Register the final public HTTPS URL.
- Ordering
- Events may arrive more than once or out of order. Compare domain state and event identity instead of relying on arrival order.
- Retry
- A numeric
Retry-Afteris honored between 30 seconds and 12 hours. Otherwise delay begins at 30 seconds and doubles to a 12-hour cap. - Disablement
- After 20 consecutive failures, the endpoint is automatically disabled and requires an authenticated configuration update.
Delivery attempts are visible to authenticated developer roles, but there is no public replay endpoint. Your receiver must be idempotent and able to recover from its own durable event record.
Current runtime inventory
Subscribe to event names emitted by the current platform.
This inventory reflects current runtime event names. Event payloads remain type-specific; confirm the exact events and payload fields assigned to your integration during access review.
Merchant and campaign4 events
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Commerce and eligibility7 events
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Claims and card lifecycle9 events
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Funding, transactions and disputes4 events
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Integrations2 events
Tenant lifecycle notification
Signed
Tenant lifecycle notification
Signed
Receiver checklist
Keep the receiver focused on verification and durable acceptance.
- 01
Read the raw body
Do not parse or normalize it before verification.
- 02
Verify headers and HMAC
Reject a missing, malformed, stale or mismatched signature.
- 03
Deduplicate by
event_idPersist the event atomically with its processing state.
- 04
Return 2xx after durable acceptance
Move slow business work to your own queue and respond within the delivery timeout.
- 05
Monitor failures
Alert on signature errors, non-2xx responses, timeouts and a rising consecutive-failure count.