Reward outcomes arrive after purchase submission, allowing your wallet to notify cardholders and update account state. Configure a receiver using the shared webhook structure, signing and delivery rules below, then follow the product guides at the end for the event payloads and business actions.
- Configure a reachable HTTPS destination and webhook signing token with Percents. The signing token is separate from your issuer API credential.
- Set up the receiver before submitting purchases so it can accept notifications as they arrive.
- Implement signature verification, durable acceptance and duplicate handling using the rules below.
| Field | Type | Purpose |
|---|---|---|
webhookId | String | Stable event identifier. Store it to prevent duplicate processing when delivery is retried. |
type | String | Event type: qualified_auth, qualified_settlement or clawback. Selects the schema of data. |
data | Object | The event's purchase and customer identifiers plus its reward, spend or clawback outcome. |
type PercentsWebhook = {
webhookId: string;
type: 'qualified_auth' | 'qualified_settlement' | 'clawback';
data: object;
};The type selects the structure of data. Use the API webhook schemas and the product guides below for the event-specific fields.
Use the issuer webhook signing token supplied by Percents, separate from your API token. Keep it server-side. The X-PERCENTS-SIGNATURE header is:
t=<epoch_milliseconds>,s=<hex_hmac_sha256_signature>Verify the HMAC-SHA256 of <timestamp>.<raw request body> using the signing token. Compare the digest in constant time before processing JSON. Validate timestamp freshness against your receiver's replay policy and synchronized clock. Also store processed webhook IDs to prevent duplicate processing. Signature verification does not deduplicate events. Coordinate signing-token rotation with Percents.
import { createHmac, timingSafeEqual } from 'node:crypto';
function verifyPercentsWebhook(
header: string | undefined,
rawBody: string,
signingToken: string,
): boolean {
const match = header?.match(/^t=(\d+),s=([a-f0-9]{64})$/i);
if (!match) {
return false;
}
const [, timestamp, signature] = match;
const expected = createHmac('sha256', signingToken)
.update(`${timestamp}.${rawBody}`)
.digest();
const received = Buffer.from(signature, 'hex');
return expected.length === received.length && timingSafeEqual(expected, received);
}The function checks only the cryptographic signature. Check timestamp freshness and deduplicate webhook IDs before business processing. Keep the original raw bytes/string for verification. JSON parsing and reserialization can change the signed body.
- Verify and durably accept each event.
- Promptly acknowledge it with a successful HTTP response. A replay of an already processed
webhookIdshould also receive success. - Complete any longer work safely after acknowledgement.
Persist identifiers and account actions together as needed to prevent duplicate credits/debits. Ignore unknown additive fields and handle new documented values explicitly.
Delivery is at least once and can be delayed or out of order. Correlate each notification with its purchase and type. An authorization estimate must not overwrite a settlement reward. Use purchase lookup for the current earn result, and branded transaction detail for spending and clawbacks when notifications arrive out of order. Deduplicate any customer account credit or reversal separately from notification receipt.
Percents attempts delivery immediately and retries failed deliveries using the configured policy. The current default maximum is five retries. After a failed delivery, the schedule below determines the wait before the next retry, if another retry is allowed. The first request is sent immediately:
| Retry Number | Wait Before Next Retry |
|---|---|
| First Request | 1 hour |
| 1 | 2 hours |
| 2 | 4 hours |
| 3 | 12 hours |
| 4 | 24 hours |
| 5 | 72 hours |
The default stops after retry 5. Its 72-hour wait applies only when additional retries are configured. A delay is not a promised completion time, and the configured maximum determines which attempts apply. After the configured retries are exhausted, do not assume automatic delivery continues.
Use the product's purchase lookup when a notification is missing or arrives out of order. An unchanged purchase retry does not create another reward event. There are no payment notifications.
qualified_auth: an estimated cashback reward based on the authorization amount, for real-time customer feedback.qualified_settlement: the actual cashback awarded for a qualifying settled purchase.
See Cashback Rewards Webhooks for payloads and how to use these results.
qualified_auth: estimated earnings, tentative branded spending or both, based on the authorization.qualified_settlement: actual merchant value earned, branded balance spent, or both. Use settled spending for customer statement credits.clawback: branded value removed and any issuer debit for value that has already been spent.
See Branded Rewards Webhooks for payloads, balance effects and account actions.