# Chargeblast Webhooks

[Chargeblast](https://chargeblast.com) helps merchants prevent chargebacks. It receives chargeback-prevention alerts (Ethoca, CDRN, RDR, TC40) and Visa Consumer Clarity / FPT deflections, and POSTs a signed JSON event to your webhook URL when an alert or deflection is created or changes. Deliveries are sent through Svix, so they carry `svix-id`, `svix-timestamp` and `svix-signature` headers.

## When to Use This Skill

* How do I receive Chargeblast webhooks?
* How do I verify a Chargeblast webhook signature (`svix-signature`)?
* Where do I find my Chargeblast webhook secret (`whsec_...`)?
* How do I handle `alert.created`, `alert.updated`, `alert.refunded` or `deflection.created` events?
* Where is the event type in a Chargeblast webhook? (Not in the body: see below.)
* Why is my Chargeblast webhook verification failing?

## Verification (core)

| Header | Value |
| --- | --- |
| `svix-id` | Identifies the message; retries reuse it |
| `svix-timestamp` | Unix seconds |
| `svix-signature` | One or more space-separated `v1,<base64>` entries |
| `X-Event-Type` | The event type, e.g. `alert.created`. **Not in the body** |

Signed content is `{svix-id}.{svix-timestamp}.{raw body}`, HMAC-SHA256, base64 output. The key is the base64-**decoded** part of the `whsec_...` secret after the prefix. Compare against every `v1,` entry; ignore other versions. If `svix-id` is absent, read `webhook-id`, `webhook-timestamp` and `webhook-signature` instead. The examples use the [`svix`](https://www.npmjs.com/package/svix) library (npm and PyPI):

```javascript
import { Webhook } from 'svix';

// rawBody: exact request body (Buffer or string), NOT re-serialised JSON
function verifyChargeblast(rawBody, headers, secret = process.env.CHARGEBLAST_WEBHOOK_SECRET) {
  const p = headers['svix-id'] ? 'svix' : 'webhook'; // fall back to the Standard Webhooks names
  const [id, timestamp, signature] = ['id', 'timestamp', 'signature'].map((k) => headers[`${p}-${k}`]);
  new Webhook(secret).verify(rawBody, {
    'svix-id': id, 'svix-timestamp': timestamp, 'svix-signature': signature,
    'webhook-id': id, 'webhook-timestamp': timestamp, 'webhook-signature': signature,
  }); // throws on a bad signature or stale timestamp → respond 400
}

```

The library always enforces a fixed **5-minute timestamp window**. Hookdeck retries and replays resend the original `svix-timestamp`, so the library rejects them once they are more than 5 minutes old. If you receive through Hookdeck and need late retries to pass, use the manual verifier in [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/chargeblast-webhooks/references/verification.md), which can drop or widen the window. In Express, read the body with `express.raw({ type: '*/*' })` so any content type verifies, and parse JSON only after the check.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/chargeblast-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/chargeblast-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/chargeblast-webhooks/examples/fastapi/).

## Event Type and Payload

There is no envelope. The body is the alert object (`alert.*` events) or the deflection object (`deflection.*` events), and the event type comes from the `X-Event-Type` header.

```json
{ "id": "al_genericId123", "alertId": "al_genericId123", "alertType": "FRAUD", "amount": 500.0,
  "currency": "usd", "subprovider": "Ethoca", "arn": "...", "authCode": "ABC123", "cardBrand": "visa",
  "customerEmail": "customer@example.com", "merchantId": "cb_genericMerchantId",
  "createdAt": "2024-10-31 21:57:23.601000Z", "transactionDate": "2024-09-30 00:00:00.000000Z" }

```

```json
{ "id": "def_4xUCdBXVs23u03i51cpQBJ", "type": "CE", "status": "Succeeded", "amount": 49.99,
  "currency": "USD", "chargeId": "ch_...", "customerEmail": "customer@example.com", "fees": 0.75,
  "merchantId": "cb_genericMerchantId" }

```

In a deflection body, `type` is the product (`CE` or `FPT`), not the event type, and `status` is `Succeeded`, `Reversed`, `Failed` or `Timeout`. Alert `externalOrder` is not available on `alert.created`; use `alert.updated`.

## Common Event Types

| Event | Fired when |
| --- | --- |
| `alert.created` | A new alert exists (also manual replay and test sends) |
| `alert.updated` | An alert that already has a matched charge changes |
| `alert.refunded` | The alert is treated as refunded; can follow `alert.created` closely. Not TC40 |
| `alert.matched` | The alert is confirmed matched to a single charge |
| `alert.will_expire` | About 46-48 hours before an Ethoca or CDRN alert expires; at most once per alert |
| `alert.within_refund_rules` | The alert falls within your automation rules; not deduplicated, and a later refund can still fail |
| `deflection.created` | A new CE or FPT deflection is created |
| `deflection.updated` | A deflection changes (for example `Succeeded` to `Reversed`, or `fees` set) |

These are the 8 documented types; the list may not be exhaustive, so ignore types you don't recognise. See [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/chargeblast-webhooks/references/overview.md).

## Delivery Semantics

Chargeblast's docs state no timeout, retry schedule or ordering guarantee. Return a `2xx` quickly, process asynchronously, and deduplicate on `svix-id` (stable across retries). Return `400` for missing headers or a bad signature. Because `alert.within_refund_rules` is not deduplicated and `alert.refunded` can arrive right after `alert.created`, make handlers idempotent and don't depend on arrival order.

## Environment Variables

```bash
CHARGEBLAST_WEBHOOK_SECRET=whsec_xxxxx   # full value from the dashboard's settings tab; handlers fail closed (500) without it

```

## Local Development

```bash
# Express / Next.js (use 8000 for FastAPI). No install or account required.
npx hookdeck-cli listen 3000 chargeblast --path /webhooks/chargeblast

```

Set the printed URL as the webhook URL in the Chargeblast dashboard's settings tab.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/chargeblast-webhooks/references/overview.md) - Event catalog, alert and deflection payload fields
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/chargeblast-webhooks/references/setup.md) - Set the webhook URL, find the secret, test
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/chargeblast-webhooks/references/verification.md) - Library and manual verification, gotchas, debugging