Webhooks

Event types

ChargebackStop currently supports five types of webhook events:

• alert.created

• alert.updated

• representment.created

• representment.updated

• fraud_notification.created

Adding webhook endpoints

In the partner dashboard

To add a webhook endpoint, go to the Partner settings page and click “Add Endpoint” in the section at the bottom of the page.

In the modal window, enter the URL ChargebackStop should send events to, and select the event types you want to receive.

Once the endpoint is saved, it appears in the table at the bottom of the page. You can use the eye icon to reveal the webhook secret that the ChargebackStop platform uses to sign webhooks.

In the organisation dashboard

Open your ChargebackStop dashboard, then select “Settings” from the left-hand menu. From the tabs at the top, pick “Webhooks”.

To add a webhook, click the “Add webhook” button and fill in the form with your endpoint URL and the events you want to receive.

Once the endpoint is saved, it appears in the table at the bottom of the page. You can use the eye icon to reveal the webhook secret that the ChargebackStop platform uses to sign webhooks.

Delivery mechanism

Request Details

• The payload will be a JSON object (see below for details).

• We include an X-Signature header, which is an HMAC-SHA512 hash of the timestamp and payload, allowing you to verify request authenticity. The signing secret is unique to your webhook subscription.

• We include an X-Idempotency-Key header with the unique delivery ID.

• We expect a successful HTTP response (2xx status code) within 20 seconds.

Reliability and retries

• If the initial delivery attempt fails (e.g., due to a network error or a 4xx/5xx response from your server), we automatically retry delivery.

• Our retry strategy includes 5 attempts over approximately 2 days, with increasing delays between attempts: 1 minute, 5 minutes, 30 minutes, 2 hours, and finally 12 hours.

  • Retries for the same delivery keep the same X-Idempotency-Key value (the delivery ID). The header helps prevent processing duplicate deliveries. To ensure you process each event only once, rely on the event ID from the payload (id), which stays the same across retries of that event.

• If all retries are exhausted and the delivery remains unsuccessful, the delivery will be marked as FAILED.

• If multiple delivery attempts to a given endpoint start failing, the system will automatically disable the webhook endpoint due to poor health.

Signature

To ensure webhook security and authenticity, we include a unique signature with each request. This signature allows you to verify that the webhook originated from us and that its payload was not tampered with in transit.

1

How the X-Signature header is generated

• Timestamp: We take the current Unix timestamp (the number of seconds since January 1, 1970 UTC). This timestamp is included directly in the signature header.

• Payload: This is the raw JSON body of the webhook request.

• Concatenation: We create a string by concatenating the timestamp, a period (.), and the UTF-8 decoded payload. For example: "{timestamp}.{payload_string}".

• HMAC-SHA512: We then use your unique webhook secret (provided to you when you set up the webhook subscription) to create an HMAC of the concatenated string using the SHA512 hashing algorithm.

• Hex Digest: The resulting HMAC is encoded into a hexadecimal string.

• Formatted signature: Finally, the signature is formatted as t={timestamp},v1={hex_digest}.

Notes on the formatted signature:

• t={timestamp}: Unix timestamp when the signature was generated. You can compare this with your current time and discard webhooks that are too old to help prevent replay attacks. We recommend tolerating reasonable clock skew (e.g., a few minutes) between your servers and ours.

• v1={hex_digest}: Signature scheme version (currently v1) followed by the hexadecimal HMAC-SHA512 digest.

2

How to verify a received signature

1. Verify the timestamp (t=): Extract the timestamp from the X-Signature header and compare it with your current server time. If the difference is too large (outside your acceptable tolerance for clock skew and message delivery times), you may choose to discard the request.

2. Verify the signature (v1=): If the timestamp is acceptable, construct the signature string on your end:

   • Use the timestamp from the t= part of the received X-Signature header.

   • Use the raw request body as the payload.

   • Concatenate them: "{timestamp_from_header}.{raw_request_body}".

   • Calculate the HMAC-SHA512 hash of this concatenated string using your webhook secret.

   • Convert the hash to its hexadecimal representation.

   • Compare this generated signature with the v1= value from the received X-Signature header. They must match exactly.

If the timestamp is recent enough and your generated signature matches the one provided in the header, you can be confident the webhook is genuine, untampered, and not a replayed request.

JavaScript signature verification function

verifySignature.js

import crypto from 'crypto';

/**
 * Verify a webhook signature.
 *
 * @param {string} rawBody            – the exact request body
 * @param {string} signatureHeader    – the entire value of the x-signature header
 * @param {string} secret             – your webhook signing secret
 * @throws {Error} on any verification failure
 */
function verifySignature(rawBody, signatureHeader, secret) {
  if (!secret) {
    throw new Error('Missing webhook secret');
  }
  if (!signatureHeader) {
    throw new Error('Missing signature header');
  }

  // e.g. "t=1618884471,v1=abcdef123456…"
  const parts = signatureHeader.split(',');
  let timestamp = null;
  let receivedSig = null;

  for (const part of parts) {
    const [key, val] = part.split('=');
    if (key === 't') {
      timestamp = val;
    } else if (key === 'v1') {
      receivedSig = val;
    }
  }

  if (!timestamp) {
    throw new Error('Signature header missing timestamp (t)');
  }
  if (!receivedSig) {
    throw new Error('Signature header missing signature (v1)');
  }

  // Enforce 5 minute tolerance
  const sentTime = Number(timestamp);
  if (Number.isNaN(sentTime)) {
    throw new Error('Invalid timestamp in signature header');
  }
  const now = Math.floor(Date.now() / 1000);
  const FIVE_MINUTES = 5 * 60;
  if (Math.abs(now - sentTime) > FIVE_MINUTES) {
    throw new Error('Timestamp is outside the allowed 5 minute window');
  }

  // Compute expected HMAC
  const payload = `${timestamp}.${rawBody}`;
  const expectedSig = crypto
    .createHmac('sha512', secret)
    .update(payload)
    .digest('hex');

  const receivedBuf = Buffer.from(receivedSig, 'hex');
  const expectedBuf = Buffer.from(expectedSig, 'hex');
  // Protect against timing attacks
  if (receivedBuf.length !== expectedBuf.length ||
      !crypto.timingSafeEqual(receivedBuf, expectedBuf)) {
    throw new Error('Invalid signature');
  }

  // All checks passed
  return true;
}

PHP signature verification function

verifySignature.php

/**
 * Verify a webhook signature.
 *
 * @param  string  $rawBody  The exact request body
 * @param  string  $signatureHeader  The value of the X-Signature header
 * @param  string  $secret  Your webhook signing secret
 *
 * @throws Exception on any verification failure
 */
function verifySignature(string $rawBody, string $signatureHeader, string $secret) : bool
{
    if (empty($secret)) {
        throw new Exception('Missing webhook secret');
    }
    if (empty($signatureHeader)) {
        throw new Exception('Missing signature header');
    }

    // Split header like "t=1618884471,v1=abcdef123456…"
    $parts = explode(',', $signatureHeader);
    $timestamp = null;
    $receivedSig = null;

    foreach ($parts as $part) {
        [$key, $val] = array_pad(explode('=', $part, 2), 2, null);
        if ('t' === $key) {
            $timestamp = $val;
        } elseif ('v1' === $key) {
            $receivedSig = $val;
        }
    }

    if (null === $timestamp) {
        throw new Exception('Signature header missing timestamp (t)');
    }
    if (null === $receivedSig) {
        throw new Exception('Signature header missing signature (v1)');
    }
    if (! ctype_digit($timestamp)) {
        throw new Exception('Invalid timestamp in signature header');
    }

    // Enforce 5 minute skew
    $sentTime = (int) $timestamp;
    $now = time();
    if (abs($now - $sentTime) > 5 * 60) {
        throw new Exception('Timestamp is outside the allowed 5 minute window');
    }

    // Compute expected signature
    $payload = $timestamp . '.' . $rawBody;
    $expectedSig = hash_hmac('sha512', $payload, $secret);

    // Timing-safe comparison
    if (! hash_equals($expectedSig, $receivedSig)) {
        throw new Exception('Invalid signature');
    }

    return true;
}

Python signature verification function

verify_signature.py

import hmac
import hashlib
import time

def verify_signature(raw_body: bytes, signature_header: str, secret: str) -> None:
    if not secret:
        raise ValueError('Missing webhook secret')
    if not signature_header:
        raise ValueError('Missing signature header')

    parts = dict(p.split('=', 1) for p in signature_header.split(',') if '=' in p)
    t = parts.get('t')
    v1 = parts.get('v1')

    if t is None:
        raise ValueError('Signature header missing timestamp (t)')
    if v1 is None:
        raise ValueError('Signature header missing signature (v1)')
    if not t.isdigit():
        raise ValueError('Invalid timestamp in signature header')

    ts = int(t)
    now = int(time.time())
    FIVE_MINUTES = 5 * 60
    if abs(now - ts) > FIVE_MINUTES:
        raise ValueError('Timestamp is outside the allowed 5 minute window')

    payload = f'{t}.{raw_body.decode("utf-8")}'.encode('utf-8')
    expected = hmac.new(secret.encode(), payload, hashlib.sha512).hexdigest()

    if not hmac.compare_digest(expected, v1):
        raise ValueError('Invalid signature')

Payloads

Webhook payload contains the following fields:

• id - unique event ID.

• type - event type, currently one of alert.created, alert.updated, representment.created, representment.updated, or fraud_notification.created.

• created_at - date and time of when event was created.

• data - object containing the main body of the event.

  • object - a snapshot of the entity the webhook was generated for. For alert events it matches the alert object from the API (https://api.chargebackstop.com/v1/docs#/Alerts/src_api_alerts_get_alerts); representment and fraud notification events follow their corresponding public event payload schemas.

  • previous_attributes - present only in ‘updated’ events, contains a list of fields that changed and their previous values.

Examples

Sample alert.created payload. data→object body matches the alert object from the API (https://api.chargebackstop.com/v1/docs#/Alerts/src_api_alerts_get_alerts).

x-signature: t=1746901125,v1=71d294712c109472c92e6afc2f0fcafce611bda73ba027f7221f8910d37b29de6fdd65489d28b28678c74d3ea62edb76f13631286d661833b0c4d4880be4d2ba
x-idempotency-key: whdl_CXwgJJye6EoZYxtFbx78Q

{
  "id": "evt_dbXKdyUWLzSP98HMVdoFW",
  "type": "alert.created",
  "created_at": "2025-05-10T18:17:35.635870+00:00",
  "data": {
    "object": {
      "id": "netalrt_yxMihZ4JhB7h5unn36F18",
      "note": null,
      "status": "ACTION_REQUIRED",
      "created_at": "2025-05-10T13:56:56.312045Z",
      "updated_at": "2025-05-10T13:56:58.111532Z",
      "merchant_id": "mrch_YoaBvAq2H2R8JYXjXodkE",
      "enrolment_type": "ETHOCA_ALERT",
      "organisation_id": "org_RoExcMDGGjmmGXKxAUAkR",
      "transaction_card_bin": null,
      "chargeback_reason_code": null,
      "transaction_card_last4": "5455",
      "transaction_network_id": null,
      "transaction_card_issuer": "BofA",
      "transaction_card_scheme": "MASTERCARD",
      "action_required_deadline": "2025-05-12T13:56:56.300274Z",
      "transaction_authorised_at": "2025-05-05T13:56:56.300274Z",
      "transaction_currency_code": "USD",
      "transaction_refund_outcome": null,
      "subscription_cancel_outcome": null,
      "transaction_amount_in_cents": 6606,
      "transaction_authorisation_code": "7XP81U",
      "transaction_statement_descriptor": "ECOM-STUFF.COM",
      "transaction_acquirer_reference_number": "012533471273304331125644612",
      "integration_id": "int_ZSHVZukGYs5SdVcwkEZrL",
		  "integration_transaction_id": "pi_3SPJO4KRFSLReU4y04XJUvLN"
    }
  },
  "api_version": "v1"
}

Sample alert.updated body. Please note the previous_attributes object.

x-signature: t=1746901218,v1=5ef9423caa3366f28eaf2411c3c3b3b6d660ddcc1a03c190ac124038e04d927bcbaae622f21c011feb27a9bae1ad96da4f74407cb1533ba1cdf8c0d8e1733b37
x-idempotency-key: whdl_ghRygm8zYiHD4vjNSQ9uT

{
  "id": "evt_NUpgzGLGJTj5j1MZ6jb1d",
  "type": "alert.updated",
  "created_at": "2025-05-10T18:20:18.430390+00:00",
  "data": {
    "object": {
      "id": "netalrt_yxMihZ4JhB7h5unn36F18",
      "note": null,
      "status": "RESOLVED",
      "created_at": "2025-05-10T13:56:56.312045Z",
      "updated_at": "2025-05-10T18:20:18.419298Z",
      "merchant_id": "mrch_YoaBvAq2H2R8JYXjXodkE",
      "enrolment_type": "ETHOCA_ALERT",
      "organisation_id": "org_RoExcMDGGjmmGXKxAUAkR",
      "transaction_card_bin": null,
      "chargeback_reason_code": null,
      "transaction_card_last4": "5455",
      "transaction_network_id": null,
      "transaction_card_issuer": "BofA",
      "transaction_card_scheme": "MASTERCARD",
      "action_required_deadline": "2025-05-12T13:56:56Z",
      "transaction_authorised_at": "2025-05-05T13:56:56Z",
      "transaction_currency_code": "USD",
      "transaction_refund_outcome": "REFUNDED",
      "subscription_cancel_outcome": null,
      "transaction_amount_in_cents": 6606,
      "transaction_authorisation_code": "7XP81U",
      "transaction_statement_descriptor": "ECOM-STUFF.COM",
      "transaction_acquirer_reference_number": "012533471273304331125644612",
      "integration_id": "int_ZSHVZukGYs5SdVcwkEZrL",
		  "integration_transaction_id": "pi_3SPJO4KRFSLReU4y04XJUvLN"
    },
    "previous_attributes": {
      "status": "ACTION_REQUIRED",
      "transaction_refund_outcome": null
    }
  },
  "api_version": "v1"
}

Sample representment.created event

{
  "id": "evt_S4VJrD42E1mVRVuCeapmt",
  "type": "representment.created",
  "created_at": "2025-05-22T19:09:09.512272+00:00",
  "data": {
    "object": {
      "id": "rep_DenAQk14kzDmwKSJn7cU3",
      "created_at": "2025-05-22T19:09:09.495869Z",
      "managed_by": "PARTNER",
      "updated_at": "2025-05-22T19:09:09.496523Z",
      "disputed_at": "2024-11-19T00:00:00",
      "merchant_id": "mrch_bQXg83B18qgACnp5Y4qU8",
      "service_type": "ONLINE_SERVICES",
      "dispute_stage": "CHARGEBACK",
      "dispute_due_by": "2024-12-03T00:00:00",
      "dispute_reason": "SUBSCRIPTION_CANCELED",
      "dispute_schema": "MASTERCARD",
      "dispute_status": "OPEN",
      "organisation_id": "org_tmo8Dq484yRUiiAcJuRPd",
      "dispute_reason_code": null,
      "dispute_reference_id": null,
      "dispute_currency_code": "USD",
      "dispute_amount_in_cents": 4444,
      "transaction_reference_id": null,
      "transaction_currency_code": "USD",
      "transaction_amount_in_cents": 4444,
      "transaction_authorisation_date": "2024-11-12T00:00:00",
      "transaction_acquirer_reference_number": null
    }
  },
  "api_version": "v1"
}

Sample representment.updated event

{
  "id": "evt_2rzszUnkDUNFiBKqe6DdT",
  "type": "representment.updated",
  "created_at": "2025-05-22T20:14:51.041381+00:00",
  "data": {
    "object": {
      "id": "rep_wMxBaE4ivxQ7zvPy1dmNx",
      "created_at": "2025-05-22T19:08:25.245116Z",
      "managed_by": "PARTNER",
      "updated_at": "2025-05-22T20:14:51.004632Z",
      "disputed_at": "2024-11-19T00:00:00",
      "merchant_id": "mrch_bQXg83B18qgACnp5Y4qU8",
      "service_type": "ONLINE_SERVICES",
      "dispute_stage": "CHARGEBACK",
      "dispute_due_by": "2024-12-03T00:00:00",
      "dispute_reason": "SUBSCRIPTION_CANCELED",
      "dispute_schema": "MASTERCARD",
      "dispute_status": "LOST",
      "organisation_id": "org_tmo8Dq484yRUiiAcJuRPd",
      "dispute_reason_code": null,
      "dispute_reference_id": null,
      "dispute_currency_code": "USD",
      "dispute_amount_in_cents": 4444,
      "transaction_reference_id": null,
      "transaction_currency_code": "USD",
      "transaction_amount_in_cents": 4444,
      "transaction_authorisation_date": "2024-11-12T00:00:00",
      "transaction_acquirer_reference_number": null
    },
    "previous_attributes": {
      "dispute_status": "OPEN"
    }
  },
  "api_version": "v1"
}

Sample fraud_notification.created event.

{
  "id": "evt_7Q19kTdTFYAQGSvT6rH4V",
  "type": "fraud_notification.created",
  "created_at": "2025-10-24T09:49:48.142333+00:00",
  "data": {
    "object": {
      "id": "frdnt_NFSPZDSTv3QgfU8GDhXKK",
      "fraud_type": "CARD_NOT_PRESENT",
      "organisation_id": "org_WVJ7aJzpT32FED9BqKPpM",
      "fraud_reported_at": "2025-08-21T08:13:50.360977Z",
      "transaction_card_bin": "411798",
      "transaction_card_last4": "3508",
      "fraud_notification_type": "SAFE",
      "transaction_merchant_id": "274953873887879",
      "transaction_currency_code": "USD",
      "transaction_merchant_name": "ECOM-STUFF OUTLET",
      "transaction_original_date": "2025-08-11T08:13:50.360977Z",
      "transaction_amount_in_cents": 14760,
      "transaction_authorisation_code": "96JNEP",
      "transaction_acquirer_reference_number": "77198913101798678449413"
    }
  },
  "api_version": "v1"
}

Field definitions:

• fraud_notification_type: SAFE or TC40

• fraud_type:

  • LOST

  • STOLEN

  • NOT_RECEIVED_AS_ISSUED

  • FRAUDULENT_APPLICATION

  • COUNTERFEIT

  • MISC

  • FRAUDULENT_USE_OF_ACCOUNT_NUMBER

  • ACQUIRER_REPORTED_COUNTERFEIT

  • INCORRECT_PROCESSING

  • ACCOUNT_TAKEOVER

  • MERCHANT_MISREPRESENTATION

  • MANIPULATION_OF_ACCOUNT_HOLDER

  • UNKNOWN

  • CARD_NOT_PRESENT

  • BUST_OUT_COLLUSIVE_MERCHANT

  • MODIFICATION_OF_PAYMENT_ORDER

  • FIRST_PARTY_MISUSE

Postman collection

We created a Postman collection that allows you to send sample webhooks.

It contains a pre-request script that generates a correct signature every time you send the request.

Postman collection: https://www.postman.com/chargebackstop/chargebackstop/collection/2yu40q8/chargebackstop-webhooks