> ## Documentation Index
> Fetch the complete documentation index at: https://test-docs.upayments.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive HTTP notifications when events happen

# Webhooks

<Note>Requires Growth tier or above</Note>

Webhooks send HTTP POST requests to your server when events happen in FinMI.

## Two Types of Events

### Payment Page & Invoice Events (Real-time)

Fired instantly when customers interact:

* `payment_page.payment` — Payment received
* `payment_page.form_start` — Customer started filling form
* `invoice.sent` — Invoice emailed to customer
* `invoice.paid` — Invoice paid
* `invoice.overdue` — Invoice past due date

### Synced Data Events (Batched)

Fired after each NMI sync cycle:

* `transaction.approved` — New approved transaction synced
* `transaction.declined` — New declined transaction synced
* `transaction.settled` — Transaction settled
* `transaction.refunded` — Refund synced
* `subscription.created` — New subscription detected
* `subscription.cancelled` — Subscription expired/cancelled
* `customer.created` — New customer extracted

<Warning>
  Synced data events fire after each sync cycle (every 15 minutes). They may include transactions that your NMI gateway already processed — these webhooks notify your system that the data is now available in FinMI.
</Warning>

## Security

All webhooks are signed with **HMAC-SHA256**. The signature is sent in the `X-Webhook-Signature` header.

Verify by computing `HMAC-SHA256(webhook_secret, request_body)` and comparing to the header value.

## Retry Policy

* Failed deliveries are retried up to 5 times
* Exponential backoff: 30s, 2m, 10m, 1h, 6h
* After 5 failures, the webhook is paused

## Creating a Webhook

1. Go to **Settings → Webhooks**
2. Click **Add Webhook**
3. Enter the endpoint URL
4. Select events to subscribe to
5. Optionally set a signing secret (recommended)

## Payload Format

```json theme={null}
{
  "event": "payment_page.payment",
  "timestamp": "2026-03-23T14:30:00Z",
  "data": {
    "transaction_id": "txn_abc123",
    "amount": 49.99,
    "currency": "USD",
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "page": {
      "id": "page_xyz",
      "title": "Premium Plan"
    }
  }
}
```