Skip to main content

​
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.
Please note that only user with full access can execute mentioned methods.

​
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.
HeaderDescriptionExample
Content-TypeSpecifies the media type of the webhook payload.application/json
User-AgentIdentifies the Finsei webhook service version.Finsei-Webhook/1.0.0 (https://api.finsei.com/doc/webhook.md)
Webhook-IdUnique identifier of the webhook delivery attempt. Useful for idempotency or debugging.0199e36e-30b8-7063-8831-1af941108e25
Webhook-TimestampUNIX timestamp (seconds) when the webhook was created by Finsei.1760457280
Webhook-SignatureHMAC-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"
  },
  "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"
  },
  "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
}
  • v1.card.create
{
  "id": 0,
  "uuid": "string",
  "wallet_id": 0,
  "wallet_uuid": "string",
  "type": "ChipAndPin",
  "masked_number": "474359******5050",
  "status": "ORDERED",
  "validUntilDate": "string",
  "cardholder_name": "string",
  "notification": {
    "type": "ERROR",
    "title": "string",
    "message": "string"
  },
  "orderInfo": {
    "title": "string",
    "message": "string",
    "ordered_at": 0,
    "dispatched_at": 0,
    "delivery": {}
  },
  "updatedAtMs": 1666666666999,
  "isSmsBalanceNotification": false,
  "designId": "AIV"
}
  • v1.card.update
{
  "id": 0,
  "uuid": "string",
  "wallet_id": 0,
  "wallet_uuid": "string",
  "type": "ChipAndPin",
  "masked_number": "474359******5050",
  "status": "ORDERED",
  "validUntilDate": "string",
  "cardholder_name": "string",
  "notification": {
    "type": "ERROR",
    "title": "string",
    "message": "string"
  },
  "orderInfo": {
    "title": "string",
    "message": "string",
    "ordered_at": 0,
    "dispatched_at": 0,
    "delivery": {}
  },
  "updatedAtMs": 1666666666999,
  "isSmsBalanceNotification": false,
  "designId": "AIV"
}
  • v2.cardLimits.calculate
{
  "purchase": {
    "transaction": {
      "value": 100
    },
    "daily": {
      "value": 200
    },
    "monthly": {
      "value": 300
    }
  },
  "withdrawal": {
    "switch": {
      "value": true
    },
    "transaction": {
      "value": 100
    },
    "daily": {
      "value": 200
    },
    "monthly": {
      "value": 300
    }
  },
  "internetPurchase": {
    "switch": {
      "value": true
    },
    "transaction": {
      "value": 100
    },
    "daily": {
      "value": 200
    },
    "monthly": {
      "value": 300
    }
  },
  "contactlessPurchase": {
    "switch": {
      "value": true
    },
    "transaction": {
      "value": 100
    },
    "daily": {
      "value": 200
    },
    "monthly": {
      "value": 300
    }
  }
}
  • v2.cardLimits.updated
{
  "id": "00000000-0000-0000-0000-000000000000",
  "updatedAt": 1667484942666
}
  • v2.cardLimits.updateError
{
  "id": "00000000-0000-0000-0000-000000000000",
  "message": "string"
}