Outbound webhooks

Receive signed events without processing the same event twice.

Rebate Card X delivers tenant lifecycle events at least once to an approved public HTTPS endpoint. Verify the raw request body, retain the event identity and acknowledge after durable acceptance so your receiver can handle repeated or out-of-order delivery.

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.

Outbound

Rebate Card X calls your endpoint

Tenant events use the signing and retry contract documented on this page.

Ingress

Providers call Rebate Card X

Approved program providers and commerce providers use separate provider-specific authentication.

Read the ingress OpenAPI
Developer access required

Webhook 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.

  1. 01

    Choose a dedicated URL

    Use a public https:// endpoint. Local, loopback and private-network targets are rejected.

  2. 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.

  3. 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.

  4. 04

    Preserve the raw request body

    Signature verification must use the exact bytes received, before JSON parsing, reformatting or field normalization.

Do not log the secret or raw customer payload

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.

HeaderValue
webhook-idDelivery-record identifier used in the signed value. Retries retain this identifier; the separate attempt counter increases.
webhook-timestampUnix epoch seconds used in the signed value.
webhook-signaturev1,<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 2xx response 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-After is 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.
Manual replay is not currently exposed

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
EVENTmerchant.kyb.submitted

Tenant lifecycle notification

Signed

EVENTmembership.created

Tenant lifecycle notification

Signed

EVENTcampaign.created

Tenant lifecycle notification

Signed

EVENTcampaign.updated

Tenant lifecycle notification

Signed

Commerce and eligibility7 events
EVENTorder.ingested

Tenant lifecycle notification

Signed

EVENTorder.updated

Tenant lifecycle notification

Signed

EVENTorder.fulfilled

Tenant lifecycle notification

Signed

EVENTorder.refunded

Tenant lifecycle notification

Signed

EVENTorder.returned

Tenant lifecycle notification

Signed

EVENTorder.ready_for_evaluation

Tenant lifecycle notification

Signed

EVENTeligibility.evaluated

Tenant lifecycle notification

Signed

Claims and card lifecycle9 events
EVENTclaim.delivery_queued

Tenant lifecycle notification

Signed

EVENTclaim.sent

Tenant lifecycle notification

Signed

EVENTrecipient.kyc.updated

Tenant lifecycle notification

Signed

EVENTcard.issuance.requested

Tenant lifecycle notification

Signed

EVENTcard.issuance_rejected

Tenant lifecycle notification

Signed

EVENTcard.issued

Tenant lifecycle notification

Signed

EVENTcard.open

Tenant lifecycle notification

Signed

EVENTcard.paused

Tenant lifecycle notification

Signed

EVENTcard.closed

Tenant lifecycle notification

Signed

Funding, transactions and disputes4 events
EVENTfunding_source.verified

Tenant lifecycle notification

Signed

EVENTfunding.updated

Tenant lifecycle notification

Signed

EVENTtransaction.updated

Tenant lifecycle notification

Signed

EVENTdispute.created

Tenant lifecycle notification

Signed

Integrations2 events
EVENTintegration.activated

Tenant lifecycle notification

Signed

EVENTintegration.external_action_required

Tenant lifecycle notification

Signed

Receiver checklist

Keep the receiver focused on verification and durable acceptance.

  1. 01

    Read the raw body

    Do not parse or normalize it before verification.

  2. 02

    Verify headers and HMAC

    Reject a missing, malformed, stale or mismatched signature.

  3. 03

    Deduplicate by event_id

    Persist the event atomically with its processing state.

  4. 04

    Return 2xx after durable acceptance

    Move slow business work to your own queue and respond within the delivery timeout.

  5. 05

    Monitor failures

    Alert on signature errors, non-2xx responses, timeouts and a rising consecutive-failure count.