Core Concepts

Overview

Understanding the following the core concepts and how Fynapse Webhooks work will help you work more effectively with them.

Core Concepts

Event

An event represents something that has happened in the system.

Example:

• balance.extracted

Subscription

A subscription defines what events you want to receive and where they should be delivered.

It binds together:

• An HTTP endpoint (your webhook receiver)
• A list of event types
• A signing secret

Each matching event will trigger a delivery attempt to the configured endpoint.

Secret

A secret is used to sign webhook requests so your system can verify that they originate from Fynapse.

• Each request includes a signature header generated using the secret
• Your system is responsible for validating this signature before processing the payload

See Webhook Security for details.

Delivery

A delivery represents a single attempt to send an event to your endpoint.

• A delivery is considered successful when your endpoint responds with a 2xx status
• Failed deliveries may be retried according to the retry policy

See Delivery & Retries for more information.

How Webhooks Work

The webhook delivery flow in Fynapse follows these steps:

1. An event occurs in the system (e.g. a balance extraction)
2. Fynapse identifies all subscriptions that match the event type
3. A delivery is created for each matching subscription
4. An HTTP POST request is sent to the configured endpoint
5. Your system processes the request and returns a response
6. Based on the response:
   • 2xx → delivery is marked as successful
   • non-2xx → delivery may be retried

Webhook Request Format

Each webhook is delivered as an HTTP POST request.

Headers

Content-Type: application/json
Webhook-Signature: used to verify the request origin
Idempotency-Key: unique identifier for the delivery

Payload

{
  "event_id": "a3efc743-ac6c-463b-aa19-4dd9c45b5b96",
  "event_type": "balance.extracted",
  "metadata": {
    "eventType": "balance.extracted",
    "startedOn": "2026-04-14T09:54:43.674940Z"
  },
  "event_timestamp": "2026-04-14T09:54:45.040Z",
  "data": {
    "...": "event-specific payload"
  }
}

Receiver Requirements

Your webhook endpoint must:

• Accept HTTP POST requests
• Accept application/json payloads
• Validate the Webhook-Signature before processing
• Handle potential duplicate deliveries using the Idempotency-Key
• Return a 2xx response as soon as possible once the message has been safely received.