Webhook Integration

Setup Webhook Subscription via API

Stream events to your system

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:

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

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.