Subscribe to webhook events

Webhooks let your application receive real-time notifications from Chargeflow without polling the API. When a subscribed event occurs, for example when a new dispute is ingested, Chargeflow sends an HTTP POST request to your configured endpoint with the event payload.

Before you start

1. Navigate to your Chargeflow Account Settings.
2. Scroll to the Developers section.
3. Generate API Access Keys. The same key is used for API requests and to sign webhook payloads.

Once your API key is available, you can register webhook endpoints either from the Chargeflow dashboard (click + Add Webhook) or via the API.

Register a webhook endpoint

POST https://api.chargeflow.io/public/2025-04-01/webhooks

Each registration subscribes one endpoint to one event (event is a single string). Register once per event you need, or pass * to subscribe one endpoint to all events.

curl -X POST https://api.chargeflow.io/public/2025-04-01/webhooks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "dispute.created", "url": "https://your-server.com/webhooks/dispute-created"}'

A successful registration returns {"success": true, "id": "..."}. See the Create Webhook reference for the full event enum.

Available events

List your webhooks

curl -X GET https://api.chargeflow.io/public/2025-04-01/webhooks \
  -H "x-api-key: YOUR_API_KEY"

Delete a webhook

curl -X DELETE https://api.chargeflow.io/public/2025-04-01/webhooks/WEBHOOK_ID \
  -H "x-api-key: YOUR_API_KEY"

Create a handler

Your endpoint must:

1. Accept POST requests with a JSON body.
2. Return a 2XX status code promptly, before any complex logic that could cause a timeout. Chargeflow retries delivery until a 2XX response is received or the retry limit is reached.
3. Process the event asynchronously after acknowledging receipt.

Example handler (Node.js / Express)

const express = require('express');
const app = express();
app.use(express.json({ type: 'application/json' }));

// One route per registered event - the URL tells you which event arrived.
app.post('/webhooks/dispute-created', (request, response) => {
  response.json({ received: true }); // acknowledge first

  const dispute = request.body.data; // enveloped: {type, data, creationDate, webhookId}
  // Trigger your enrichment flow asynchronously:
  // enrichDispute(dispute.id);
});

app.post('/webhooks/alerts-created', (request, response) => {
  response.json({ received: true });

  const alert = request.body; // flat payload - no envelope
  // alert.id, alert.type (e.g. 'fraud_warning'), alert.status, alert.outcome
  // Initiate refund or mitigation workflow:
  // handleAlert(alert.id);
});

app.listen(8000, () => console.log('Webhook handler running on port 8000'));

Signature verification and delivery

For signature verification and delivery/retry behavior, see Webhooks.

Testing webhooks

After saving your webhook registration, you can send a mock payload at any time to validate your integration:

• Click the Test button next to your webhook endpoint in the Chargeflow dashboard, or
• Access the actions menu for the registered endpoint and select Send Test Payload.

Chargeflow will deliver a sample event payload to your endpoint. Check that your handler responds with 200 OK and processes the payload correctly.

Next steps