> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargeblast.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks
> This page will help you get started with our webhooks.
### Headers
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**.
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.
The individual merchant this alert belongs to. You can call the [Fetch Merchants](/api-reference/enrollment/fetch-merchants) endpoint to get all possible merchant IDs for your account.
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`.
The alert network or source. See [Alert Types](/reference/alert-types) for all possible values.
Deflection product: `CE` (Consumer Clarity) or `FPT`.
One of `Succeeded`, `Reversed`, `Failed`, `Timeout`.
Billed deflection fee in dollars when set; may be null until billing runs.
The individual merchant this deflection belongs to (same id space as alert `merchantId`). You can call the [Fetch Merchants](/api-reference/enrollment/fetch-merchants) endpoint to list merchant IDs for your account.
```json Alert theme={null}
{
"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"
}
```
```json Deflection theme={null}
{
"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](/api-reference/webhooks/webhook-events) 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.
```Javascript theme={null}
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](/api-reference/webhooks/webhook-events)**
***
### Related
* [Webhook event types](/api-reference/webhooks/webhook-events) — Full event-type reference (alerts and deflections)
* [Alert Types](/reference/alert-types) — Full list of alert networks and subprovider values
* [Reason Codes](/reference/reason-codes) — Codes used when actioning alerts
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.