Webhooks

Headers

string

Event name for this delivery, for example alert.created, alert.updated, deflection.created, or deflection.updated.

Body

Alert events (alert.*) and deflection events (deflection.*) use different JSON bodies. Use the tabs below for field definitions; the example on the right switches between Alert and Deflection.

Alert
Deflection

Show properties

string

float

object

Dictionary of string keys and string values for optional metadata on the alert (for example order number, processor id). Same field appears on webhook payloads and on alert objects returned from the Alerts API.

string

bool

string

The individual merchant this alert belongs to. You can call the Fetch Merchants endpoint to get all possible merchant IDs for your account.

string

The card network transaction ID for the disputed transaction. Useful for matching the alert against the network transaction ID your payment processor reports. Optional — only present when the alert network provides it, so keep fallback matching on arn, authCode, card, amount, and transactionDate.

string

The alert network or source. See Alert Types for all possible values.

string

Show properties

string

Deflection product: CE (Consumer Clarity) or FPT.

string

One of Succeeded, Reversed, Failed, Timeout.

float

string

float

Billed deflection fee in dollars when set; may be null until billing runs.

string

The individual merchant this deflection belongs to (same id space as alert merchantId). You can call the Fetch Merchants endpoint to list merchant IDs for your account.

{
    "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",
    "creditAppealed": false,
    "creditStatus": "None",
    "currency": "usd",
    "customerEmail": "customer@example.com",
    "customerId": "cus_genericId456",
    "descriptor": "GENERIC TXN12345",
    "externalOrder": "ch_genericOrder789",
    "externalUrl": "https://example.com/charges/ch_genericOrder789",
    "id": "al_genericId123",
    "issuer": "Generic Bank, Inc.",
    "merchantId": "cb_genericMerchantId",
    "networkId": "542418161516789787",
    "provider": "exampleProvider",
    "reasonCode": "Resolved",
    "responseAction": "Accepted",
    "site": "example.com",
    "subprovider": "Ethoca",
    "transactionDate": "2024-09-30 00:00:00.000000Z"
}

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

First set up your webhook URL in the Chargeblast dashboard in the settings tab.

Chargeblast will begin emitting events to your webhook URL. Switch the example above between Alert and Deflection, or see Webhook event types for when each X-Event-Type fires.

The externalOrder field is not available in the alert.created event. Please use the alert.updated event if you require this field.

Authentication

To authenticate the integrity of incoming webhooks, a header is passed into the post request to your endpoint under the header name svix-signature. The value in this header is an HMAC-SHA256 encoded string using the payload of the request with the webhook secret as key. In order to authenticate the request, you perform a HMAC-SHA256 encoding using a concat of webhook request body, svix_timestamp and svix_id and your webhook secret (whsec_xxxxxxxxxxxx) and ensure these strings match. Then input string to SHA256 HMAC will look like: signedContent = "${svix_id}.${svix_timestamp}.${body}" This is a common method for ensuring that the webhook messages you receive in your server are from a trusted source and haven’t been tampered with.

const crypto = require('crypto');

const signedContent = `${svix_id}.${svix_timestamp}.${body}`;
const secret = "whsec_xxxxxxxx";

// Need to base64 decode the secret
const secretBytes = Buffer.from(secret.split('\_')[1], "base64");
const signature = crypto
.createHmac('sha256', secretBytes)
.update(signedContent)
.digest('base64');

console.log(signature);

The svix-signature header is composed of a list of space delimited signatures and their corresponding version identifiers. The signature list is most commonly of length one. Though there could be any number of signatures. For example: v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo= Make sure to remove the version prefix and delimiter (e.g. v1,) before verifying the signature. Use v1. In this example, you’d compare your signature against bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo=.

Types

Chargeblast emits several X-Event-Type values, including alert events (alert.created, alert.updated, alert.refunded, alert.matched, alert.will_expire, alert.within_refund_rules) and deflection events (deflection.created, deflection.updated). The guide below documents when each event fires and which alert or deflection types apply: Webhook event types

Webhook event types — Full event-type reference (alerts and deflections)
Alert Types — Full list of alert networks and subprovider values
Reason Codes — Codes used when actioning alerts

Welcome

Guides

Platform

Alerts

Digital Receipts & Deflections

RDR

Enrollment

Headers

Body

Authentication

Types

​Headers

​Body

​Authentication

​Types

​Related

Headers

Body

Authentication

Types

Related