How can I get webhooks?

Webhook subscription setup

To setup endpoint and subscribe to webhook events you should execute PATCH /v2/webhook method. The following parameters should be specified in request body:

url - the path to the service you’ll receive your webhooks on
enable - whether or not webhook send is enabled
rateLimit - amount of events per second
events - the list of events you subscribe to

The list of available events can be obtained in GET /v2/webhook/event method.

In order to check if everything is configured correctly, execute GET /v2/webhook method.

Any company user can execute the method and configure a webhook for themselves with the required pool of events and with their own url.

Webhook retry

If a webhook delivery attempt fails, the system will automatically try to resend the message at the following time intervals after the initial failure:

5 seconds
5 minutes (300 seconds)
30 minutes (1800 seconds)
2 hours (7200 seconds)
5 hours (18000 seconds)
10 hours (36000 seconds)

Webhook Headers

Each webhook request sent from Finsei includes several HTTP headers that help ensure security, integrity, and traceability of events.

Header	Description	Example
`Content-Type`	Specifies the media type of the webhook payload.	`application/json`
`User-Agent`	Identifies the Finsei webhook service version.	`Finsei-Webhook/1.0.0 (https://api.finsei.com/doc/webhook.md)`
`Webhook-Id`	Unique identifier of the webhook delivery attempt. Useful for idempotency or debugging.	`0199e36e-30b8-7063-8831-1af941108e25`
`Webhook-Timestamp`	UNIX timestamp (seconds) when the webhook was created by Finsei.	`1760457280`
`Webhook-Signature`	HMAC-based signature to verify the authenticity and integrity of the payload.	`aqpd2Y8elIDUwXcouBeD7bSMEb8ttedxNXif8pWq19Ghiu3rR5JbPV2gNDhNKAm…`

Webhook example values

v2.payment.create

{
  "id": 0,
  "uuid": "string",
  "status": "new",
  "type": "string",
  "fee": {
    "amount": 0,
    "currencyId": "str"
  },
  "amount": 0,
  "total": 0,
  "counterparty": {
    "name": "string",
    "accountHolderName": "string",
    "bic": "string",
    "iban": "string"
  },
  "beneficiaryId": 0,
  "walletId": 0,
  "walletUuid": "string",
  "icon": "CONVERT",
  "entity": "PAYMENT",
  "currencyId": "str",
  "currencyExchangeId": 0,
  "currencyExchangeUuid": "string",
  "reference": "string",
  "transactionAmount": 0,
  "transactionCurrencyId": "str",
  "transactionExchangeRate": "string",
  "retrievalReferenceNumber": "string",
  "rejectReason": "string",
  "purposeCode": {
    "code": "string",
    "purpose": "string"
  },
  "operationType": "string",
  "createdAt": 1666666666999,
  "updatedAt": 1666666666999,
  "completedAt": 1667404598000
}

v2.payment.update

{
  "id": 0,
  "uuid": "string",
  "status": "new",
  "type": "string",
  "fee": {
    "amount": 0,
    "currencyId": "str"
  },
  "amount": 0,
  "total": 0,
  "counterparty": {
    "name": "string",
    "accountHolderName": "string",
    "bic": "string",
    "iban": "string"
  },
  "beneficiaryId": 0,
  "walletId": 0,
  "walletUuid": "string",
  "icon": "CONVERT",
  "entity": "PAYMENT",
  "currencyId": "str",
  "currencyExchangeId": 0,
  "currencyExchangeUuid": "string",
  "reference": "string",
  "transactionAmount": 0,
  "transactionCurrencyId": "str",
  "transactionExchangeRate": "string",
  "retrievalReferenceNumber": "string",
  "rejectReason": "string",
  "purposeCode": {
    "code": "string",
    "purpose": "string"
  },
  "operationType": "string",
  "createdAt": 1666666666999,
  "updatedAt": 1666666666999,
  "completedAt": 1667404598000
}

v2.payment.delete

{
"id": 0,
"uuid": "string",
"walletId": 0,
"walletUuid": "string"
}

v3.wallet.create

{
  "id": 0,
  "uuid": "string",
  "balance": 0,
  "balanceLock": 0,
  "balanceInProgress": 0,
  "currencyId": "str",
  "description": "string",
  "data": {
    "type": "BANK",
    "accountId": "string",
    "details": [
      {
        "id": "string",
        "isMain": true,
        "label": "string",
        "iban": "string",
        "bicSwift": "string",
        "bank": {
          "accountHolderName": "string",
          "name": "string",
          "address": "string"
        }
      }
    ]
  },
  "flags": {
    "isVisible": true,
    "isFavourite": true
  },
  "status": "ACTIVE",
  "color": "string",
  "name": "string",
  "updatedAt": 1666666666999
}

v3.wallet.update

{
  "id": 0,
  "uuid": "string",
  "balance": 0,
  "balanceLock": 0,
  "balanceInProgress": 0,
  "currencyId": "str",
  "description": "string",
  "data": {
    "type": "BANK",
    "accountId": "string",
    "details": [
      {
        "id": "string",
        "isMain": true,
        "label": "string",
        "iban": "string",
        "bicSwift": "string",
        "bank": {
          "accountHolderName": "string",
          "name": "string",
          "address": "string"
        }
      }
    ]
  },
  "flags": {
    "isVisible": true,
    "isFavourite": true
  },
  "status": "ACTIVE",
  "color": "string",
  "name": "string",
  "updatedAt": 1666666666999
}

v2.card.create

{
  "id": "string",
  "walletId": "string",
  "type": "ChipAndPin",
  "maskedPan": "474359******5050",
  "status": "PROCESS",
  "validUntilDate": "string",
  "cardholderName": "string",
  "notification": {
    "type": "ERROR",
    "title": "string",
    "message": "string"
  },
  "orderInfo": {
    "title": "string",
    "message": "string",
    "orderedAt": 0,
    "dispatchedAt": 0,
    "delivery": {}
  },
  "isSmsBalanceNotification": false,
  "designId": "AIV",
  "updatedAt": 1666666666,
  "version": 1
}

v2.card.update

{
  "id": "string",
  "walletId": "string",
  "type": "ChipAndPin",
  "maskedPan": "474359******5050",
  "status": "PROCESS",
  "validUntilDate": "string",
  "cardholderName": "string",
  "notification": {
    "type": "ERROR",
    "title": "string",
    "message": "string"
  },
  "orderInfo": {
    "title": "string",
    "message": "string",
    "orderedAt": 0,
    "dispatchedAt": 0,
    "delivery": {}
  },
  "isSmsBalanceNotification": false,
  "designId": "AIV",
  "updatedAt": 1666666666,
  "version": 1
}

v2.cardLimits.calculate

{
  "withdrawal": {
      "currencyId": "EUR",
      "switch": {
        "enabled": true,
        "value": true
      },
      "transaction": {
        "default": 1500,
        "max": 3000,
        "value": 1500
      },
      "daily": {
        "default": 1500,
        "max": 3000,
        "value": 1500,
        "used": 0,
        "available": 1500,
        "reset": 1774483200
      },
      "monthly": {
        "default": 5000,
        "max": 10000,
        "value": 5000,
        "used": 0,
        "available": 5000,
        "reset": 1775001600
      }
    },
    "internetPurchase": {
      "currencyId": "EUR",
      "switch": {
        "enabled": true,
        "value": true
      },
      "transaction": {
        "default": 2000,
        "max": 12500,
        "value": 2000
      },
      "daily": {
        "default": 4000,
        "max": 25000,
        "value": 4000,
        "used": 0,
        "available": 4000,
        "reset": 1774483200
      },
      "monthly": {
        "default": 10000,
        "max": 50000,
        "value": 10000,
        "used": 0,
        "available": 10000,
        "reset": 1775001600
      }
    },
    "contactlessPurchase": {
      "currencyId": "EUR",
      "switch": {
        "enabled": true,
        "value": true
      },
      "transaction": {
        "default": 1000,
        "max": 12500,
        "value": 1000
      },
      "daily": {
        "default": 2000,
        "max": 25000,
        "value": 2000,
        "used": 0,
        "available": 2000,
        "reset": 1774483200
      },
      "monthly": {
        "default": 10000,
        "max": 50000,
        "value": 10000,
        "used": 0,
        "available": 10000,
        "reset": 1775001600
      }
  }
}

v2.cardLimits.updated

{
  "id": "00000000-0000-0000-0000-000000000000",
  "updatedAt": 1667484942666
}

v2.cardLimits.updateError

{
  "id": "00000000-0000-0000-0000-000000000000",
  "message": "string"
}

​Webhook subscription setup

​Webhook retry

​Webhook Headers

​Webhook example values

​v2.payment.create

​v2.payment.update

​v2.payment.delete

​v3.wallet.create

​v3.wallet.update

​v2.card.create

​v2.card.update

​v2.cardLimits.calculate

​v2.cardLimits.updated

​v2.cardLimits.updateError