> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fynapse.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fynapse.app/_mcp/server.

# Core Concepts

> Understanding Fynapse Webhook Core Concepts and how they work.

## 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"
  }
}
```

| Field           | Description                            |
| --------------- | -------------------------------------- |
| event_id        | Unique identifier of the event         |
| event_type      | Type of event                          |
| metadata        | Additional technical information       |
| event_timestamp | When the event occurred                |
| data            | Business payload specific to the event |

## 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.

> **Info**
>
> We strongly advise that processing of the data is completed asynchronously

## Watch a Video about Webhooks' Core Concepts