Setup Webhook Subscription via API | Fynapse Documentation

Overview

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

Please note that Balance Extract webhook requires an additional step of configuring an extract in the UI. This additional step is described in Event Types

Before You Start

Make sure you are familiar with:

Webhook concepts → Webhooks Overview
Request validation → Webhook Security
Delivery behavior and retries → Delivery & Retries
API access and permissions → Webhook Configuration

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

curl -X POST https://api.fynapse.com/api/v1/event-deliveries/secrets \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "string"
}'

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

curl -X POST https://api.fynapse.com/api/v1/event-deliveries/subscriptions \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Balance Webhook",
  "endpointUrl": "https://example.com/webhooks/balance",
  "eventTypes": [
    "balance.extracted"
  ]
}'

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

eventTypeslist of stringsRequired

List of event types to subscribe to. At least one type is required.

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.

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:

The list of available Event Types can be found here

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.