Webhook Integration

Balance Extracts via Webhook

Stream balance extract events to your system

Overview

This guide explains how to receive balance extract events in your system using webhooks.

You will configure a webhook subscription and connect it to a balance extract so that events are delivered automatically when extracts are executed.

Before You Start

Make sure you are familiar with:

Step 1 — Create a Webhook Secret

A webhook secret is used to sign requests so your system can verify their authenticity.

Create a secret using the API:

POST
/api/v1/event-deliveries/secrets
1curl -X POST https://api.fynapse.com/api/v1/event-deliveries/secrets \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "name": "webhook-signing-secret"
6}'
Try it
  • Store the returned value property securely.
  • You will need it to validate webhook signatures.

Step 2 — Create a Webhook Subscription

A subscription defines where events should be delivered.

POST
/api/v1/event-deliveries/subscriptions
1curl -X POST https://api.fynapse.com/api/v1/event-deliveries/subscriptions \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "name": "Balance Webhook",
6  "endpointUrl": "https://example.com/webhooks/orders"
7}'
Try it

Here you will need to provide:

Request

namestringRequired1-255 characters
Unique name of the subscription
endpointUrlstringRequired>=1 character
Target URL for the webhook delivery
secretRefstring or nullOptional
Reference name of the secret to use for signing. If omitted on create, a secret is auto-created with the subscription name.
eventTypeslist of stringsOptional
Optional list of event types to subscribe to. If null or empty, all event types are received.
descriptionstringOptional<=1024 characters
Optional description

Step 3 — Configure Your Receiver

Your webhook endpoint must:

  • Accept POST requests
  • Accept application/json payloads
  • Validate the webhook signature
  • Handle duplicate deliveries using the Idempotency-Key

See:

Step 4 — Create a Balance Extract with Webhook Target

You will need Extractions Editor role assigned, e.g. Editor, to create the extract on the Extracts screen.

  • Go to Operations → Extracts → Extracts in Fynapse
  • Create a new extract
  • Set Target name to Webhook
  • Select Balances as the data source
  • Complete the configuration
  • Wait for schedule to Activate or run the extract manually

See Data Extraction for more details.

When the extract runs, balance.extracted events are generated and delivered to your webhook endpoint.

Event Format

Each delivery contains a balance.extracted event

Please note that the contents of the data property will be based off your selected Balance Query.

1{
2  "event_id": "a3efc743-ac6c-463b-aa19-4dd9c45b5b96",
3  "event_type": "balance.extracted",
4  "metadata": {
5    "eventType": "balance.extracted",
6    "startedOn": "2026-04-14T09:54:43.674940Z",
7    "extractConfigurationName": "test"
8  },
9  "event_timestamp": "2026-04-14T09:54:45.040Z",
10  "data": {
11    "node": "Node1",
12    "account": "222",
13    "balance": 1.0,
14    "productName": "",
15    "transactionCurrency": "GBP"
16  }
17}

Testing the Integration

To verify your setup:

  • Trigger a balance extract manually
  • Confirm your endpoint receives the request
  • Validate the signature
  • Ensure the event is processed successfully

If the endpoint does not return 2xx, the delivery will be retried automatically.