Guide to Chargeblast Webhooks: Features and Best Practices
Chargeblast helps merchants stop chargebacks before they are filed. It collects pre-dispute alerts from the card networks' programmes (Ethoca, CDRN, RDR and TC40) and runs Visa Consumer Clarity and FPT deflections, which answer a cardholder's query with order details so the dispute never happens. Many of those alerts have to be acted on quickly, often with a refund, so Chargeblast's webhooks are usually wired straight into an order or refund system.
This guide explains Chargeblast's alert and deflection events, why you route on a header rather than the body, how to verify the Svix signature, and what Chargeblast leaves undocumented about delivery.
What are Chargeblast webhooks?
You set one webhook URL in the Chargeblast dashboard, and Chargeblast posts JSON to it whenever an alert or deflection is created or changes. Delivery runs on Svix, so each request carries svix-id, svix-timestamp and svix-signature, signed with the Standard Webhooks scheme.
The event name travels in a fourth header, X-Event-Type. The body doesn't contain it. Alert events send the alert object and deflection events send the deflection object, and the deflection's own type field (CE or FPT) is the deflection product, which is easy to mistake for the event type.
Chargeblast webhook features
| Feature | Details |
|---|---|
| Configuration | Dashboard settings tab |
| Subscription model | One URL. No per-event selection documented |
| Delivery platform | Svix |
| Headers | svix-id, svix-timestamp, svix-signature, X-Event-Type |
| Signature | Standard Webhooks HMAC-SHA256, v1,<base64> |
| Secret | whsec_... from the settings tab |
| Body | The alert object or the deflection object, no envelope |
| Event routing | X-Event-Type header |
| Timeout, retries, ordering | Not documented |
| Source IPs | Not published |
Events and payloads
| Event type | Alert types | Fires when |
|---|---|---|
alert.created | Ethoca, CDRN, RDR, TC40 | A new alert exists and a "created" notification is emitted. Also sent for manual replays and tests |
alert.updated | Ethoca, CDRN, RDR, TC40 | The alert was updated in a way that should notify subscribers and it already has a matched charge |
alert.refunded | Ethoca, CDRN, RDR | The system treats the alert as refunded (or, on some Verifi paths, ingested already resolved/refunded) |
alert.matched | Ethoca, CDRN, RDR, TC40 | The alert is confirmed matched to a single charge |
alert.will_expire | Ethoca, CDRN | About 46-48 hours before the alert expires, for eligible WIP alerts that still need attention |
alert.within_ | Ethoca, CDRN, RDR | The alert is within your configured automation rules |
deflection.created | CE, FPT | A new deflection record is created |
deflection.updated | CE, FPT | An existing deflection changes, such as a CE status change or billing |
Chargeblast attaches rules to several of these. alert.updated is never sent for an alert without a matched charge. alert.will_expire is sent at most once per alert. alert.within_ is not deduplicated and isn't always followed by alert.refunded, because the refund can still fail. alert.refunded can arrive moments after alert.created when the network delivers an alert that is already resolved.
An alert body looks like this (abbreviated from Chargeblast's example):
{
"alertId": "al_genericId123",
"alertType": "FRAUD",
"amount": 500.00,
"attributes": { "order_number": "#1533", "processor_id": "proc_b381c83a9bc8a93" },
"arn": "12345678901234567890123",
"authCode": "ABC123",
"card": "123456xxxxxxx7890",
"cardBrand": "visa",
"createdAt": "2024-10-31 21:57:23.601000Z",
"currency": "usd",
"customerEmail": "customer@example.com",
"id": "al_genericId123",
"merchantId": "cb_genericMerchantId",
"networkId": "542418161516789787",
"provider": "exampleProvider",
"reasonCode": "Resolved",
"responseAction": "Accepted",
"subprovider": "Ethoca",
"transactionDate": "2024-09-30 00:00:00.000000Z"
}
networkId is optional, so keep fallback matching on arn, authCode, card, amount and transactionDate. externalOrder, your own order reference, is not present on alert.created; Chargeblast says to use alert.updated if you need it.
A deflection body is much smaller: id, type (CE for Consumer Clarity or FPT), status (Succeeded, Reversed, Failed or Timeout), amount, currency, chargeId, customerEmail, fees and merchantId. fees stays null until billing runs, which is one of the reasons deflection.updated fires.
Setting up Chargeblast webhooks
- In the Chargeblast dashboard, open the settings tab.
- Enter your HTTPS endpoint, for example
https://example.com/webhooks/chargeblast, and save. Chargeblast starts sending every event type to it. - Copy the webhook secret shown there (
whsec_...) and store it asCHARGEBLAST_, including the prefix.WEBHOOK_ SECRET
Chargeblast doesn't document a validation request or a test button, but alert.created is also sent for manual replays and test sends from its tooling. For local work, expose your receiver with the Hookdeck CLI:
npx hookdeck-cli listen 3000 chargeblast --path /webhooks/chargeblast
With Hookdeck. Set up a Chargeblast source in Hookdeck with the whsec_ secret and give Chargeblast the source URL. Only POST is accepted. Chargeblast always sees a 200 from Hookdeck, and a request that fails the signature check is recorded there as failed verification rather than passed to your service.
Securing Chargeblast webhooks
Chargeblast prints the Svix construction on its webhooks page: the signed content is ${svix_, and the key is your secret. In practice that means the base64-decoded part after whsec_, and the header can hold several v1, signatures separated by spaces. This verifier handles both and falls back to webhook-* header names:
const crypto = require('node:crypto');
function decodeBase64(value) {
if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
const bytes = Buffer.from(value, 'base64');
return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
? bytes : null;
}
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const prefix = headers['svix-id'] ? 'svix' : 'webhook';
const id = headers[`${prefix}-id`];
const timestamp = headers[`${prefix}-timestamp`];
const signature = headers[`${prefix}-signature`];
if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
!/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
const key = decodeBase64(secret.replace(/^whsec_/, ''));
if (!key) return false;
const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
const received = decodeBase64(candidate);
if (!received) return false;
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
Route on the header after verifying. Keep alert and deflection bodies apart, because they are different objects:
const express = require('express');
// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
try {
const value = JSON.parse(rawBody.toString('utf8'));
return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
} catch {
return null;
}
}
const app = express();
app.post('/webhooks/chargeblast', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.CHARGEBLAST_WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
const eventType = req.get('x-event-type');
if (!eventType) return res.sendStatus(400);
const body = parseJsonObject(req.body);
if (!body) return res.sendStatus(400); // signed, but not a JSON object
try {
if (eventType.startsWith('deflection.')) {
if (!body.id) return res.sendStatus(400);
await deflections.upsert(body.id, body.status, body.fees);
} else if (eventType === 'alert.created' || eventType === 'alert.will_expire') {
if (!body.alertId) return res.sendStatus(400);
await alertQueue.add({ eventType, alertId: body.alertId, arn: body.arn, amount: body.amount });
}
} catch {
return res.sendStatus(503); // not processed, so don't acknowledge
}
return res.sendStatus(200);
});
deflections and alertQueue represent your own storage and queue.
Chargeblast sets no timestamp tolerance of its own. The svix library, if you use it instead of the code above, refuses timestamps more than 5 minutes old. Hookdeck doesn't check timestamp age, and it forwards Chargeblast's original svix-timestamp on retries and replays, so keep that library window off for traffic that passes through Hookdeck.
Make Chargeblast webhooks production-ready. Hookdeck Event Gateway verifies every Chargeblast alert, keeps a copy with its
X-Event-Type, and retries delivery to your refund workflow until it succeeds.
Chargeblast webhook limitations and pain points
No published retry policy
The Problem: You can't tell whether an alert that hit your endpoint during an outage will be sent again.
Why It Happens: Chargeblast's docs give no timeout, retry schedule or disabling rule. Svix normally retries, but Chargeblast doesn't say how it is configured.
Workarounds:
- Answer quickly and do the refund work afterwards.
- Reconcile open alerts through Chargeblast's Alerts API, which returns the same
attributesand fields as the webhook.
How Hookdeck Can Help: Hookdeck accepts and stores each alert when it arrives, then retries delivery to your service on a schedule you know.
The event type isn't in the body
The Problem: A queue consumer that only stored the body can't tell alert.created from alert.refunded.
Why It Happens: Chargeblast sends the name in X-Event-Type only.
Workarounds:
- Copy
X-Event-Typeinto the message you enqueue, as the handler above does. - Don't confuse a deflection's
typefield with the event type.
How Hookdeck Can Help: Hookdeck keeps every header with the event and its filters can match on X-Event-Type, so each event type can go to its own destination.
Some events repeat and some don't
The Problem: Your refund logic runs twice, or waits for an event that never comes.
Why It Happens: alert.within_ has no deduplication and can repeat. alert.updated is skipped for unmatched alerts. alert.will_expire doesn't cover RDR or TC40.
Workarounds:
- Make refund actions idempotent per
alertId. - Don't depend on
alert.updateduntil the alert is matched, and track expiry yourself for RDR and TC40.
How Hookdeck Can Help: Hookdeck's deduplication can drop repeated deliveries by svix-id. Repeats that Chargeblast sends as new messages still need idempotent handling on your side.
alert.created lacks your order reference
The Problem: You can't link a new alert to an order straight away.
Why It Happens: externalOrder is only filled in from alert.updated onwards.
Workarounds:
- Match new alerts on
arn,authCode, card, amount andtransactionDate, or onnetworkIdwhen present. - Wait for
alert.matchedoralert.updatedwhen you need the order ID.
How Hookdeck Can Help: Hookdeck's event history lets you look back at an alert's earlier events when the later one finally carries the order reference.
Best practices
Treat alerts as time-sensitive
Alert programmes have deadlines, which is why alert.will_expire exists. Queue alert events for immediate handling and alert a person on alert.will_expire rather than just logging it.
Verify against the raw body
Read the request with express.raw({ type: '*/*' }), await request.text() in a Next.js route handler, or await request.body() in FastAPI, and switch off CSRF middleware on the route. Parsing first changes the bytes.
Deduplicate on svix-id
Use the svix-id header for delivery-level duplicates and alertId or the deflection id for business-level ones. For a fuller treatment, read our guide to webhook idempotency.
Don't assume order
Chargeblast makes no ordering promise, and alert.refunded can come right after alert.created. Store the latest status per alert and ignore transitions that move it backwards.
Conclusion
Chargeblast's webhooks carry money-sensitive alerts with deadlines, through a standard Svix signature and an unusual header-based event type. Verify with the whsec_ secret, read X-Event-Type before you parse, keep alert and deflection handling separate, and build idempotent refund logic, since several events can repeat or arrive in quick succession.
With no published retry policy, the safest setup accepts every alert straight away. Hookdeck Event Gateway can do that, verify each request and queue it for your refund system. Try Hookdeck free with your Chargeblast account.