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

# Webhook Callback

> Receives FinCard webhook events. Verifies platform signature.



## OpenAPI

````yaml post /api/v2.1/fincard/virtual/webhook/callback
openapi: 3.1.0
info:
  title: Business BFF API
  version: 1.0.0
  description: Backend for Frontend - Business Panels Orchestration Layer
servers:
  - url: https://sandbox.finhub.cloud
    description: Sandbox Environment
security: []
tags:
  - name: AML
    description: Anti-Money Laundering checks and transaction monitoring
  - name: Admin - Consent Management
    description: Operations for managing consent templates and definitions
  - name: B2B Customer - Organization
    description: B2B organization registration and management
  - name: B2C Customer - Individual
    description: Individual customer registration and lifecycle management
  - name: BFF Admin - Tenant Initialization
    description: Lazy tenant initialization for fast startup
  - name: Catalog Hierarchy
    description: Hierarchical catalog management APIs
  - name: Catalog-Process Mapping
    description: APIs for catalog-process relationship management
  - name: Consent
    description: Payment consent creation and approval
  - name: Draft Management
  - name: External Events
    description: Kafka-to-HTTP bridge event ingestion and query
  - name: FinCard Virtual - Webhooks
    description: FinCard Virtual Card Webhook receiver
  - name: FinCard Virtual Account
    description: FinCard Virtual Card Account API proxy
  - name: FinCard Virtual Card Holder
    description: FinCard Virtual Card Holder API proxy
  - name: FinCard Virtual Cards
    description: FinCard Virtual Card API proxy
  - name: FinCard Virtual Common
    description: FinCard Virtual Card Common API proxy
  - name: FinCard Virtual Wallet
    description: FinCard Virtual Card Wallet API v2 proxy
  - name: FinTrans - Operations
    description: Financial transaction operations
  - name: Internal Webhooks
    description: Internal service-to-service webhook trigger (HMAC-secured)
  - name: MFE Preload
    description: MFE preload endpoints for SSR optimization
  - name: MFE Registry
    description: MFE Registry management endpoints
  - name: Payment Consent Management
    description: Operations for managing payment consents and validation
  - name: Person
    description: Person details for process context
  - name: Products
    description: Product Catalog Management API
  - name: Reference Data
    description: Shared reference data (countries, etc.)
  - name: Tenant Lifecycle
    description: Tenant mode transitions and lifecycle management
  - name: Tenant Registration
    description: Self-registration and tenant onboarding
  - name: Transfers
    description: Transfer prepare/execute aliases for muse-proxy compatibility
  - name: Verification
    description: Customer verification (KYC/KYB/AML) management
  - name: Wallet
    description: Wallet operations and balance management
  - name: Webhooks
    description: Webhook subscription and delivery management
paths:
  /api/v2.1/fincard/virtual/webhook/callback:
    post:
      tags:
        - FinCard Virtual - Webhooks
      summary: Webhook Callback
      description: Receives FinCard webhook events. Verifies platform signature.
      parameters:
        - description: FinCard platform signature
          name: X-WSB-SIGNATURE
          in: header
          schema:
            type: string
      requestBody:
        description: Webhook event data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEventData'
        required: true
      responses:
        '200':
          description: Webhook processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCallbackResponse'
        '400':
          description: Bad request
        '401':
          description: Invalid signature
        '500':
          description: Internal server error
components:
  schemas:
    WebhookEventData:
      type: object
      description: Webhook event data
      properties:
        eventType:
          type: string
          examples:
            - CARD_OPERATION_TRANSACTION
          description: Event type
          example: CARD_OPERATION_TRANSACTION
        eventId:
          type: string
          examples:
            - evt-12345678
          description: Event ID
          example: evt-12345678
        timestamp:
          type: integer
          format: int64
          examples:
            - 1640995200000
          description: Timestamp
          example: 1640995200000
        tenantId:
          type: string
          examples:
            - wsb-12345678
          description: Tenant ID
          example: wsb-12345678
        accountId:
          type: string
          examples:
            - wsb-account-123
          description: Account ID
          example: wsb-account-123
        cardId:
          type: string
          examples:
            - card-12345678
          description: Card ID (for card events)
          example: card-12345678
        cardholderId:
          type: string
          examples:
            - ch-12345678
          description: Cardholder ID (for cardholder events)
          example: ch-12345678
        transactionId:
          type: string
          examples:
            - tx-12345678
          description: Transaction ID (for transaction events)
          example: tx-12345678
        workOrderId:
          type: string
          examples:
            - wo-12345678
          description: Work order ID (for work order events)
          example: wo-12345678
        status:
          type: string
          examples:
            - COMPLETED
          description: Event status
          example: COMPLETED
        result:
          type: string
          examples:
            - SUCCESS
          description: Event result
          example: SUCCESS
        data:
          type: object
          additionalProperties: {}
          description: Event data payload
        errorMessage:
          type: string
          examples:
            - Insufficient funds
          description: Error message (if any)
          example: Insufficient funds
        errorCode:
          type: string
          examples:
            - INSUFFICIENT_FUNDS
          description: Error code (if any)
          example: INSUFFICIENT_FUNDS
        retryCount:
          type: integer
          format: int32
          examples:
            - 0
          description: Retry count
          example: 0
        maxRetries:
          type: integer
          format: int32
          examples:
            - 3
          description: Max retries
          example: 3
    WebhookCallbackResponse:
      type: object
      description: Webhook callback response
      properties:
        success:
          type: boolean
          examples:
            - true
          description: Success flag
          example: true
        code:
          type: integer
          format: int32
          examples:
            - 200
          description: Response code
          example: 200
        msg:
          type: string
          examples:
            - Success
          description: Response message
          example: Success
        eventId:
          type: string
          examples:
            - evt-12345678
          description: Processed event ID
          example: evt-12345678
        processingTime:
          type: integer
          format: int64
          examples:
            - 1640995200000
          description: Processing time
          example: 1640995200000

````