Gareth Wilson Gareth Wilson

Guide to Chargeblast Webhooks: Features and Best Practices

Published


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

FeatureDetails
ConfigurationDashboard settings tab
Subscription modelOne URL. No per-event selection documented
Delivery platformSvix
Headerssvix-id, svix-timestamp, svix-signature, X-Event-Type
SignatureStandard Webhooks HMAC-SHA256, v1,<base64>
Secretwhsec_... from the settings tab
BodyThe alert object or the deflection object, no envelope
Event routingX-Event-Type header
Timeout, retries, orderingNot documented
Source IPsNot published

Events and payloads

Event typeAlert typesFires when
alert.createdEthoca, CDRN, RDR, TC40A new alert exists and a "created" notification is emitted. Also sent for manual replays and tests
alert.updatedEthoca, CDRN, RDR, TC40The alert was updated in a way that should notify subscribers and it already has a matched charge
alert.refundedEthoca, CDRN, RDRThe system treats the alert as refunded (or, on some Verifi paths, ingested already resolved/refunded)
alert.matchedEthoca, CDRN, RDR, TC40The alert is confirmed matched to a single charge
alert.will_expireEthoca, CDRNAbout 46-48 hours before the alert expires, for eligible WIP alerts that still need attention
alert.within_refund_rulesEthoca, CDRN, RDRThe alert is within your configured automation rules
deflection.createdCE, FPTA new deflection record is created
deflection.updatedCE, FPTAn 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_refund_rules 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

  1. In the Chargeblast dashboard, open the settings tab.
  2. Enter your HTTPS endpoint, for example https://example.com/webhooks/chargeblast, and save. Chargeblast starts sending every event type to it.
  3. Copy the webhook secret shown there (whsec_...) and store it as CHARGEBLAST_WEBHOOK_SECRET, including the prefix.

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_id}.${svix_timestamp}.${body}, 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 attributes and 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-Type into the message you enqueue, as the handler above does.
  • Don't confuse a deflection's type field 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_refund_rules 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.updated until 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 and transactionDate, or on networkId when present.
  • Wait for alert.matched or alert.updated when 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.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.