Webhooks

Finup can send server-to-server webhook events to your HTTPS endpoint after account activity changes. Subscribe once per account, get the signing secret from the subscription details endpoint, and verify every delivery with the x-webhook-signature header.

Webhook subscription endpoints use API key authentication. Send your API key in the x-api-key header. They need API access enabled for the account (otherwise 403 with API_ACCESS_DISABLED) and the can_manage_api_keys permission.

Create a subscription with the URL that should receive webhook events. The URL must resolve to a public address: private, loopback and other internal ranges are rejected.

curl --request POST "https://api.finup.io/backend/webhooks" \
  --header "x-api-key: $FINUP_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/finup/webhooks"
  }'

The response contains the created subscription record.

{
  "result": {
    "_id": "67fc3d0a766d7a2c1fafefb8",
    "url": "https://example.com/finup/webhooks",
    "status": "enabled",
    "account": "67fc3d0a766d7a2c1fafefb9",
    "secret": "f2933800c06e7ed7c1b1fd01c8a8165d9851174b5651f1f2aef5429a7a13aa2d"
  }
}

Use GET /webhooks after creation as the source for the usable plaintext signing secret. Do not use the create or update response as the source of truth for signature verification. Only one subscription is allowed per account. Creating a second subscription returns 404 with Account Already subscribed.

Manage a subscription

Get the current subscription and plaintext signing secret:

curl --request GET "https://api.finup.io/backend/webhooks" \
  --header "x-api-key: $FINUP_API_KEY"

{
  "result": {
    "_id": "67fc3d0a766d7a2c1fafefb8",
    "url": "https://example.com/finup/webhooks",
    "status": "enabled",
    "account": "67fc3d0a766d7a2c1fafefb9",
    "secret": "f2933800c06e7ed7c1b1fd01c8a8165d9851174b5651f1f2aef5429a7a13aa2d"
  }
}

Without a subscription, result is an empty array. Store secret server-side. Use it to verify the x-webhook-signature header on every delivery. Update the destination URL or pause delivery:

curl --request PATCH "https://api.finup.io/backend/webhooks" \
  --header "x-api-key: $FINUP_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/new-webhook-url",
    "status": "enabled"
  }'

Use status: "disabled" to pause delivery. Disabled subscriptions do not receive new webhook events. If the account has no subscription yet, PATCH /webhooks creates one and returns it like POST /webhooks. When a subscription already exists, a successful update returns:

{
  "result": {
    "status": "SUCCESS",
    "code": 200
  }
}

There is no delete endpoint and no separate secret rotation endpoint. If you need a new secret, contact support.

Delivery format

Finup sends a POST request to your subscription URL.

Content-Type: application/json
x-webhook-signature: <hex HMAC SHA-256>

The signature is HMAC-SHA256(JSON.stringify(body), secret) encoded as lowercase hex. Verify against the exact JSON body Finup sent.

import crypto from "node:crypto";

function verifyFinupWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(body))
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Return any 2xx response within 10 seconds when your system has accepted the event. Redirects are not followed, so a 3xx counts as a failed attempt. Delivery history keeps the status code and time of every attempt.

Retries

Finup sends the first attempt immediately. If your endpoint returns a non-2xx response or the request fails, the event remains pending and is retried.

Failed attempt	Next retry delay
Initial send	1 minute
1	2 minutes
2	2 minutes
3	5 minutes
4	20 minutes
5	30 minutes
6	60 minutes
7	240 minutes
8	360 minutes

After the final retry fails, the delivery status becomes fail. A successful retry changes the delivery status to success. Your endpoint should be idempotent. Finup may deliver the same event more than once when a previous attempt failed or timed out.

Delivery history

Use delivery history to inspect sent events, retry status, and the status code of each attempt.

curl --request POST "https://api.finup.io/backend/webhooks/history" \
  --header "x-api-key: $FINUP_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "pagination": {
      "page": 1,
      "per_page": 50,
      "sort_by": "last_sending",
      "sort_direction": "desc"
    }
  }'

Each history item includes:

Field	Description
`body`	Webhook payload sent to your endpoint
`config`	Delivery headers, including the signature used for the attempt
`responses`	Status code and time of each attempt
`last_sending`	Last attempt time
`next_sending`	Next retry time while status is `pending`
`attempts`	Number of attempts already made
`status`	`pending`, `success`, or `fail`

Example response:

{
  "result": [
    {
      "_id": "67fc3d0a766d7a2c1fafefc1",
      "body": {
        "id": "67c48f6fc8614632e0b338fc",
        "masked_PAN": "1234 56** **** 5678",
        "name": "Marketing card",
        "account_id": "67fc3d0a766d7a2c1fafefb9",
        "status": "enabled",
        "updated_at": "2026-07-08T12:00:00.000Z",
        "webhook_type": "CardUpdate"
      },
      "config": {
        "Content-Type": "application/json",
        "x-webhook-signature": "ab12cd34..."
      },
      "responses": [
        {
          "status_code": 200,
          "time": "2026-07-08T12:00:00.000Z"
        }
      ],
      "url": "https://example.com/finup/webhooks",
      "last_sending": "2026-07-08T12:00:00.000Z",
      "next_sending": "null",
      "attempts": 1,
      "status": "success",
      "subscribe": "67fc3d0a766d7a2c1fafefb8"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_records": 1,
    "total_pages": 1
  }
}

Event types

Every event has a webhook_type field. Use it to route the payload. Backend currently emits CardUpdate. The Webhooks microservice also uses the same account subscription for Transaction, Deposit, Otp, and OtpWallet.

CardUpdate

Sent when the Backend service updates card status data.

{
  "id": "67c48f6fc8614632e0b338fc",
  "masked_PAN": "1234 56** **** 5678",
  "name": "Marketing card",
  "account_id": "67fc3d0a766d7a2c1fafefb9",
  "status": "enabled",
  "updated_at": "2026-07-08T12:00:00.000Z",
  "webhook_type": "CardUpdate"
}

Transaction

Sent when a card transaction is created or updated. status, side and type use the same values as POST /transactions.

{
  "id": "69289796211cd0ba00ecc9db",
  "account_id": "6878f06012024f0a66f1b833",
  "card_id": "6900c4a4611a0d534ad72956",
  "status": "approved",
  "side": "debit",
  "amount": 30,
  "currency": "USD",
  "type": "card_transaction",
  "created_at": "2026-07-08T12:00:00.000Z",
  "updated_at": "2026-07-08T12:00:00.000Z",
  "card": {
    "id": "6900c4a4611a0d534ad72956",
    "masked_PAN": "4549 24** **** 4124",
    "name": "App Devs"
  },
  "card_data": {
    "merchant_name": "VYKE HOLDING LIMITED",
    "original_amount": 30,
    "original_currency": "USD",
    "decline_code": null
  },
  "webhook_type": "Transaction"
}

Deposit

Sent when a crypto or invoice deposit is approved, when a deposit is blocked by the AML check (Declined), and when a blocked deposit has been refunded (Canceled).

{
  "id": "69289796211cd0ba00ecc9db",
  "account_id": "6878f06012024f0a66f1b833",
  "status": "Approved",
  "amount": 100,
  "fee_amount": 1,
  "currency": "USD",
  "created_at": "2026-07-08T12:00:00.000Z",
  "updated_at": "2026-07-08T12:00:00.000Z",
  "reference": "USD2156306518",
  "webhook_type": "Deposit"
}

Otp

Sent when a payment OTP is created for a card.

{
  "id": "67fc3d0a766d7a2c1fafefc1",
  "account_id": "67fc3d0a766d7a2c1fafefb9",
  "code": "123456",
  "card_id": "67c48f6fc8614632e0b338fc",
  "amount": 30,
  "currency": "USD",
  "created_at": "2026-07-08T12:00:00.000Z",
  "updated_at": "2026-07-08T12:00:00.000Z",
  "card": {
    "id": "67c48f6fc8614632e0b338fc",
    "masked_PAN": "1234 56** **** 5678",
    "name": "Marketing card"
  },
  "webhook_type": "Otp"
}

OtpWallet

Sent when an Apple Pay or Google Pay wallet OTP is created for a card.

{
  "id": "67fc3d0a766d7a2c1fafefc1",
  "account_id": "67fc3d0a766d7a2c1fafefb9",
  "code": "123456",
  "card_id": "67c48f6fc8614632e0b338fc",
  "device": "apple",
  "created_at": "2026-07-08T12:00:00.000Z",
  "updated_at": "2026-07-08T12:00:00.000Z",
  "card": {
    "id": "67c48f6fc8614632e0b338fc",
    "masked_PAN": "1234 56** **** 5678",
    "name": "Marketing card"
  },
  "webhook_type": "OtpWallet"
}

Start

MCP

Manage a subscription

Delivery format

Retries

Delivery history

Event types

CardUpdate

Transaction

Deposit

Otp

OtpWallet

​Subscribe

​Manage a subscription

​Delivery format

​Retries

​Delivery history

​Event types

​CardUpdate

​Transaction

​Deposit

​Otp

​OtpWallet

Subscribe

Manage a subscription

Delivery format

Retries

Delivery history

Event types

CardUpdate

Transaction

Deposit

Otp

OtpWallet