Agent skill

Chargeblast Webhooks Skill

Receive and verify Chargeblast webhooks, which are delivered by Svix. Use when setting up a Chargeblast webhook endpoint, getting the whsec_ webhook secret, debugging svix-id / svix-timestamp / svix-signature verification, or handling chargeback-prevention alert and deflection events like alert.created, alert.updated, alert.refunded, alert.will_expire and deflection.created.

Install this skill

npx skills add hookdeck/webhook-skills --skill chargeblast-webhooks


Chargeblast 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)

HeaderValue
svix-idIdentifies the message; retries reuse it
svix-timestampUnix seconds
svix-signatureOne or more space-separated v1,<base64> entries
X-Event-TypeThe 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 library (npm and PyPI):

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, 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/, examples/nextjs/, 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.

{ "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" }
{ "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

EventFired when
alert.createdA new alert exists (also manual replay and test sends)
alert.updatedAn alert that already has a matched charge changes
alert.refundedThe alert is treated as refunded; can follow alert.created closely. Not TC40
alert.matchedThe alert is confirmed matched to a single charge
alert.will_expireAbout 46-48 hours before an Ethoca or CDRN alert expires; at most once per alert
alert.within_refund_rulesThe alert falls within your automation rules; not deduplicated, and a later refund can still fail
deflection.createdA new CE or FPT deflection is created
deflection.updatedA 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.

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

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

Local Development

# 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →