Webhooks

Configure and listen to webhook events produced by Chargeflow to automatically notify your system of changes and trigger reactions.

Why webhooks

When integrating with Chargeflow, your application may need to receive real-time notifications for specific events, such as when a new dispute is created. Webhooks provide this capability by allowing you to register an HTTP endpoint that Chargeflow calls whenever a subscribed event occurs.

By using webhooks, your application can respond immediately to new events without relying on periodic API polling. This improves efficiency, reduces unnecessary API calls, and ensures your system remains up to date in real time.

Enabling webhooks

After registration, Chargeflow sends webhook events as HTTP POST requests to your specified endpoint. A successful delivery is confirmed when your endpoint responds with a 2XX status code (preferably 200). If any other response is received, Chargeflow will retry delivery until a 2XX response is returned or the retry limit is reached.

Payload shapes differ by event. dispute.created (and the platform integration.access.error) arrive wrapped in an envelope - {type, data, creationDate, webhookId} - where type is the event name and data carries the resource. The three alert events are delivered flat, with no envelope: their type field holds the alert type (for example fraud_warning), not the event name. See the event payload reference before writing your handler.

Event authentication

Each webhook POST request from Chargeflow includes an HMAC signature in the X-Chargeflow-Hmac-Sha256 header, derived from the body, path, and method of the request.

You can use this signature to verify the authenticity and integrity of the request on your side, ensuring you only react to genuine Chargeflow calls and not unauthorized third-party requests to your public endpoint.

The Secret Key used to sign (and verify) webhook requests is available on the Chargeflow Settings page alongside other webhook configurations. Note: the API Secret Key is currently the same as the primary API Access Key secret.

This page is the canonical home for verifying inbound webhook deliveries (below). Signing your own outbound requests to the Chargeflow API uses the same HMAC construction and is documented in Authentication.

Verifying a webhook signature

const crypto = require('crypto');

function generateHmacSignature(data, secretKey) {
  const hmac = crypto.createHmac('sha256', secretKey);
  hmac.update(data);
  return hmac.digest('hex');
}

function verifySignature(req) {
  const receivedSig = req.headers['x-chargeflow-hmac-sha256'];

  const method = req.method;
  const path = req.originalUrl;
  const body = JSON.stringify(req.body);

  const dataToSign = `${method}\n${path}\n${body}`;
  const secret = 'your_secret_key'; // Obtain from Chargeflow Settings
  const hash = generateHmacSignature(dataToSign, secret);

  return receivedSig === hash;
}

Configuring webhooks

// This example uses Express to receive webhooks
const express = require('express');
const app = express();

// Match the raw body to content type application/json
// If you are using Express v4 - v4.16 you need to use body-parser, not express, to retrieve the request body
app.post('/webhook', express.json({ type: 'application/json' }), (request, response) => {
  const event = request.body;

  // Optionally validate request signature against body from x-chargeflow-hmac-sha256 header

  // Handle the event. Only enveloped events (dispute.created) carry the
  // event name in `type` - alert payloads are flat and their `type` is the
  // alert type, so route alert events by registering a dedicated URL per event.
  if (event.type === 'dispute.created') {
    const disputeCreated = event.data;
    // Then define and call a method to handle the dispute created event data.
    // handleDisputeCreated(disputeCreated);
  }

  // Return a response to acknowledge receipt of the event
  response.json({ received: true });
});

app.listen(8000, () => console.log('Running on port 8000'));

Webhook event topics

Next steps