# Guide to Chargeblast Webhooks: Features and Best Practices

[Chargeblast](https://www.chargeblast.com) 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_refund_rules` | 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_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):

```json
{
  "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](/docs/cli):

```bash
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](https://docs.chargeblast.com/api-reference/webhooks/setup): 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:

```javascript
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:

```javascript
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](/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](/docs/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](/docs/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](/docs/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](/webhooks/guides/implement-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](https://hookdeck.com) can do that, verify each request and queue it for your refund system. [Try Hookdeck free](https://dashboard.hookdeck.com/signup) with your Chargeblast account.