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.refundedordeflection.createdevents? - 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 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
| 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_ | 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.
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_ 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
- references/overview.md - Event catalog, alert and deflection payload fields
- references/setup.md - Set the webhook URL, find the secret, test
- references/verification.md - Library and manual verification, gotchas, debugging