Wise Webhook Event API

openapi: 3.2.0
info:
  title: Wise Platform Webhook Event API
  version: ''
  description: "The Wise Platform API is a REST-based interface that enables programmatic access to Wise's payment infrastructure. All endpoints return JSON-formatted responses and use standard HTTP methods and status codes.\n{% admonition type=\"success\" name=\"New to wise?\" %}\n  We strongly recommend first reading our **[Getting Started Guide](/guides/developer/index.md)** to help you set up credentials and make your first call.\n{% /admonition %}\n\nBefore you begin {% .title-2 .m-t-5 %}\n\nTo use this API reference effectively, you should have:\n\n- Received Valid [API credentials from Wise](/guides/developer/auth-and-security/index.md) (Client ID and Client Secret)\n- Understand OAuth 2.0 authentication\n- Be familiar with RESTful API concepts\n\nCore API resources {% .title-2 .m-t-5 .m-b-0 %}\n\n| Resource | Purpose |\n|----------|---------|\n| **[Quote](/api-reference/quote)** | Exchange rate and fee calculations |\n| **[Recipient](/api-reference/recipient)** | Beneficiary account management |\n| **[Transfer](/api-reference/transfer)** | Payment creation and execution |\n| **[Balance](/api-reference/balance)** | Multi-currency account operations |\n| **[Profile](/api-reference/profile)** | Account ownership details |\n| **[Rate](/api-reference/rate)** | Current and historical exchange rates |\n\n**Not sure which workflow to build?**<br>\nStart with our [Integration Guides](/guides/product/send-money/use-cases/index.md) for step-by-step implementation examples.{% .m-t-3 .m-b-5 %}\n"
servers:
- url: https://api.wise.com
  description: Production Environment
- url: https://api.wise-sandbox.com
  description: Sandbox Environment
tags:
- name: webhook-event
  x-displayName: Events
  description: 'Webhook events are notifications sent by Wise to your server when specific actions occur. Subscribe to events using the [Webhook](/api-reference/webhook) endpoints at the application or profile level.


    See the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.


    {% admonition type="info" %}

    We''re migrating event type documentation to this section. For a complete list of available event types, see the [Event Types](/guides/developer/webhooks/event-types) guide.

    {% /admonition %}

    '
paths: {}
webhooks:
  transfers#state-change:
    post:
      operationId: eventTransfersStateChange
      summary: Transfer state change
      description: 'Triggered every time a transfer''s status is updated.

        See the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.


        Events may not be delivered in the order they occurred. Use `data.occurred_at` to reconcile the order.

        See the [Event Ordering](/guides/developer/webhooks/event-ordering) guide for details.


        {% admonition type="warning" %}

        For topup-to-balance transfers, `transfers#state-change` events will **not** be triggered.

        To listen to these, subscribe to the `balances#update` event instead.

        {% /admonition %}


        * Event type: `transfers#state-change`

        * Profile level subscriptions: Supported

        * Application level subscriptions: Supported

        '
      tags:
      - webhook-event
      parameters:
      - $ref: '#/components/parameters/x-signature-sha256'
      - $ref: '#/components/parameters/x-delivery-id'
      - $ref: '#/components/parameters/x-test-notification'
      requestBody:
        content:
          application/json:
            schema:
              title: Transfer State Change Event
              discriminator:
                propertyName: schema_version
                mapping:
                  4.0.0: '#/components/schemas/v4.0.0'
                  2.0.0: '#/components/schemas/v2.0.0'
              oneOf:
              - $ref: '#/components/schemas/v4.0.0'
              - $ref: '#/components/schemas/v2.0.0'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
          description: Return any `2xx` status to acknowledge receipt of the event.
  transfers#active-cases:
    post:
      operationId: eventTransfersActiveCases
      summary: Transfer active cases
      description: 'Triggered every time a transfer''s list of active cases is updated.

        Active cases indicate potential problems with transfer processing.

        See the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.


        * Event type: `transfers#active-cases`

        * Profile level subscriptions: Supported

        * Application level subscriptions: Supported

        '
      tags:
      - webhook-event
      parameters:
      - $ref: '#/components/parameters/x-signature-sha256'
      - $ref: '#/components/parameters/x-delivery-id'
      - $ref: '#/components/parameters/x-test-notification'
      requestBody:
        content:
          application/json:
            schema:
              title: Transfer Active Cases Event
              discriminator:
                propertyName: schema_version
                mapping:
                  4.0.0: '#/components/schemas/v4.0.0-2'
                  2.0.0: '#/components/schemas/v2.0.0-2'
              oneOf:
              - $ref: '#/components/schemas/v4.0.0-2'
              - $ref: '#/components/schemas/v2.0.0-2'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
          description: Return any `2xx` status to acknowledge receipt of the event.
  account-details-payment#state-change:
    post:
      operationId: eventAccountDetailsPaymentStateChange
      summary: Account details payment state change
      description: 'Triggered every time a pay-in is made into the specified account details.

        See the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.


        Events may not be delivered in the order they occurred. Use `data.occurred_at` to reconcile the order.

        See the [Event Ordering](/guides/developer/webhooks/event-ordering) guide for details.


        * Event type: `account-details-payment#state-change`

        * Profile level subscriptions: Supported

        * Application level subscriptions: Supported

        '
      tags:
      - webhook-event
      parameters:
      - $ref: '#/components/parameters/x-signature-sha256'
      - $ref: '#/components/parameters/x-delivery-id'
      - $ref: '#/components/parameters/x-test-notification'
      requestBody:
        content:
          application/json:
            schema:
              title: Account Details Payment State Change Event
              discriminator:
                propertyName: schema_version
                mapping:
                  4.0.0: '#/components/schemas/v4.0.0-3'
                  2.0.0: '#/components/schemas/v2.0.0-3'
              oneOf:
              - $ref: '#/components/schemas/v4.0.0-3'
              - $ref: '#/components/schemas/v2.0.0-3'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
          description: Return any `2xx` status to acknowledge receipt of the event.
  cards#manual-provisioning-verification:
    post:
      operationId: eventCardsManualProvisioningVerification
      summary: Cards manual provisioning verification
      description: 'Triggered when a card is manually added to a wallet provider, and the verification methods required to complete the wallet provisioning are returned.

        See the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.


        * Event type: `cards#manual-provisioning-verification`

        * Profile level subscriptions: Not Supported

        * Application level subscriptions: Supported

        '
      tags:
      - webhook-event
      parameters:
      - $ref: '#/components/parameters/x-signature-sha256'
      - $ref: '#/components/parameters/x-delivery-id'
      - $ref: '#/components/parameters/x-test-notification'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v2.0.0-4'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
          description: Return any `2xx` status to acknowledge receipt of the event.
  hold-limit-breach#update:
    post:
      operationId: eventHoldLimitBreachUpdate
      summary: Hold limit breach update
      description: 'Triggered whenever a hold limit breach is opened or closed for a profile. A hold limit breach occurs when a balance exceeds the regulatory hold limit (applicable in countries such as Singapore and Malaysia).

        See the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.


        Events may not be delivered in the order they occurred. Use `data.occurred_at` to reconcile the order.

        See the [Event Ordering](/guides/developer/webhooks/event-ordering) guide for details.


        Use `data.state` to determine whether the breach has been opened or closed, and `data.closing_reason` to understand how it was resolved.


        * Event type: `hold-limit-breach#update`

        * Profile level subscriptions: Supported

        * Application level subscriptions: Supported

        '
      tags:
      - webhook-event
      parameters:
      - $ref: '#/components/parameters/x-signature-sha256'
      - $ref: '#/components/parameters/x-delivery-id'
      - $ref: '#/components/parameters/x-test-notification'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v4.0.0-4'
            examples:
              breachOpened:
                summary: Breach opened
                value:
                  schema_version: 4.0.0
                  subscription_id: 01234567-89ab-cdef-0123-456789abcdef
                  event_type: hold-limit-breach#update
                  sent_at: '2024-06-01T08:00:00Z'
                  data:
                    resource:
                      type: hold-limit-breach
                      hold_limit_breach_id: 1001
                      profile_id: 12321323
                    amount: 500.5
                    currency: SGD
                    state: OPEN
                    closing_reason: null
                    created_at: '2024-06-01T08:00:00Z'
                    updated_at: '2024-06-01T08:00:00Z'
                    occurred_at: '2024-06-01T08:00:00Z'
              breachClosed:
                summary: Breach closed
                value:
                  schema_version: 4.0.0
                  subscription_id: 01234567-89ab-cdef-0123-456789abcdef
                  event_type: hold-limit-breach#update
                  sent_at: '2024-06-02T09:15:00Z'
                  data:
                    resource:
                      type: hold-limit-breach
                      hold_limit_breach_id: 1001
                      profile_id: 12321323
                    amount: 500.5
                    currency: SGD
                    state: CLOSED
                    closing_reason: MANUALLY_RESOLVED
                    created_at: '2024-06-01T08:00:00Z'
                    updated_at: '2024-06-02T09:15:00Z'
                    occurred_at: '2024-06-02T09:15:00Z'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
          description: Return any `2xx` status to acknowledge receipt of the event.
components:
  schemas:
    v4.0.0-3:
      title: Schema version 4.0.0
      type: object
      properties:
        schema_version:
          type: string
          description: Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook).
          enum:
          - 4.0.0
          example: 4.0.0
        subscription_id:
          type: string
          format: uuid
          description: ID of the webhook subscription that triggered this event
          example: 36c3f762-560d-4f07-84f9-5d8a3cacabbb
        event_type:
          type: string
          description: Event type identifier
          example: account-details-payment#state-change
        sent_at:
          type: string
          format: date-time
          description: Timestamp when the event was sent
          example: '2024-01-01T12:34:56.123Z'
        data:
          type: object
          properties:
            resource:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
                  description: Balance ID which is linked to the account detail
                  example: 12345
                profile_id:
                  type: integer
                  format: int64
                  description: ID of the profile that owns the payment
                  example: 1
                type:
                  type: string
                  description: Type of the resource
                  example: balance-account
            account_details_id:
              type: string
              description: Account detail ID where the pay-in was received
              example: '1'
            target_account_id:
              type: string
              description: Balance ID which is linked to the account detail
              example: '12345'
            transfer:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
                  description: ID of the incoming transfer
                  example: 36454
                type:
                  type: string
                  description: Type of the transfer
                  example: credit
                amount:
                  type: number
                  format: decimal
                  description: Transfer amount
                  example: 120
                currency:
                  type: string
                  description: Currency code
                  example: EUR
            sender:
              type: object
              properties:
                name:
                  type: string
                  description: Sender name
                  example: Test Sender
                account_number:
                  type: string
                  description: Sender account number
                  example: '12345678'
                bank_code:
                  type: string
                  description: Sender bank code
                  example: TESTBANK
                address:
                  type: string
                  description: Sender address
                  example: Test Address
            current_state:
              type: string
              description: Current state of the payment
              enum:
              - PROCESSING
              - COMPLETED
              - CANCELLED
              - REFUNDED
              example: COMPLETED
            previous_state:
              type: string
              description: Previous state of the payment
              enum:
              - PROCESSING
              - COMPLETED
              - CANCELLED
              - REFUNDED
              example: PROCESSING
            occurred_at:
              type: string
              format: date-time
              description: Timestamp when the event occurred
              example: '2026-02-24T11:10:13.789Z'
    v4.0.0-2:
      title: Schema version 4.0.0
      type: object
      properties:
        schema_version:
          type: string
          description: Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook).
          enum:
          - 4.0.0
          example: 4.0.0
        subscription_id:
          type: string
          format: uuid
          description: ID of the webhook subscription that triggered this event
          example: 01234567-89ab-cdef-0123-456789abcdef
        event_type:
          type: string
          description: Event type identifier
          example: transfers#active-cases
        sent_at:
          type: string
          format: date-time
          description: Timestamp when the event was sent
          example: '2020-01-01T12:34:56.123Z'
        data:
          type: object
          properties:
            resource:
              type: object
              properties:
                type:
                  type: string
                  description: Resource type
                  example: transfer
                id:
                  type: integer
                  format: int64
                  description: Transfer ID
                  example: 111
                profile_id:
                  type: integer
                  format: int64
                  description: Profile ID of the transfer owner
                  example: 222
                account_id:
                  type: integer
                  format: int64
                  description: Recipient account ID
                  example: 333
            active_cases:
              type: array
              items:
                type: string
              description: Ongoing issues related to the transfer
              example:
              - deposit_amount_less_invoice
    v4.0.0:
      title: Schema version 4.0.0
      type: object
      properties:
        schema_version:
          type: string
          description: Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook).
          enum:
          - 4.0.0
          example: 4.0.0
        subscription_id:
          type: string
          format: uuid
          description: ID of the webhook subscription that triggered this event
          example: 01234567-89ab-cdef-0123-456789abcdef
        event_type:
          type: string
          description: Event type identifier
          example: transfers#state-change
        sent_at:
          type: string
          format: date-time
          description: Timestamp when the event was sent
          example: '2020-01-01T12:34:56.123Z'
        data:
          type: object
          properties:
            resource:
              type: object
              properties:
                type:
                  type: string
                  description: Resource type
                  example: transfer
                id:
                  type: integer
                  format: int64
                  description: Transfer ID
                  example: 111
                profile_id:
                  type: integer
                  format: int64
                  description: Profile ID of the transfer owner
                  example: 222
                account_id:
                  type: integer
                  format: int64
                  description: Recipient account ID
                  example: 333
            current_state:
              type: string
              description: 'Current transfer status. See [Transfer Statuses](/guides/product/send-money/tracking-transfers) for possible values.

                '
              example: processing
            previous_state:
              type:
              - string
              - 'null'
              description: Previous transfer status. Note that this will be null for newly created transfers.
              example: incoming_payment_waiting
            occurred_at:
              type: string
              format: date-time
              description: Timestamp when the state change occurred
              example: '2020-01-01T12:34:56.789Z'
    v4.0.0-4:
      title: Schema version 4.0.0
      type: object
      properties:
        schema_version:
          type: string
          description: Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook).
          enum:
          - 4.0.0
          example: 4.0.0
        subscription_id:
          type: string
          format: uuid
          description: ID of the webhook subscription that triggered this event
          example: 01234567-89ab-cdef-0123-456789abcdef
        event_type:
          type: string
          description: Event type identifier
          example: hold-limit-breach#update
        sent_at:
          type: string
          format: date-time
          description: Timestamp when the event was sent
          example: '2024-06-01T08:00:00Z'
        data:
          type: object
          properties:
            resource:
              type: object
              properties:
                type:
                  type: string
                  description: Resource type. Always `hold-limit-breach`
                  example: hold-limit-breach
                hold_limit_breach_id:
                  type: integer
                  format: int64
                  description: ID of the hold limit breach
                  example: 1001
                profile_id:
                  type: integer
                  format: int64
                  description: ID of the profile that owns the breach
                  example: 12321323
            amount:
              type: number
              format: decimal
              description: Amount that exceeded the hold limit
              example: 500.5
            currency:
              type: string
              description: Currency code (ISO 4217) of the breach amount
              example: SGD
            state:
              type: string
              description: Current state of the breach
              enum:
              - OPEN
              - CLOSED
              example: CLOSED
            closing_reason:
              type:
              - string
              - 'null'
              description: Reason the breach was closed. Null if state is `OPEN`
              enum:
              - AUTOMATICALLY_RESOLVED
              - MANUALLY_RESOLVED
              - null
              example: MANUALLY_RESOLVED
            created_at:
              type: string
              format: date-time
              description: Timestamp when the breach was created (ISO 8601)
              example: '2024-06-01T08:00:00Z'
            updated_at:
              type: string
              format: date-time
              description: Timestamp when the breach was last updated (ISO 8601)
              example: '2024-06-01T08:00:00Z'
            occurred_at:
              type: string
              format: date-time
              description: Timestamp when the event occurred (ISO 8601). Use this field to reconcile out-of-order events
              example: '2024-06-01T08:00:00Z'
    v2.0.0:
      title: Schema version 2.0.0
      type: object
      properties:
        schema_version:
          type: string
          description: Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook).
          enum:
          - 2.0.0
          example: 2.0.0
        subscription_id:
          type: string
          format: uuid
          description: ID of the webhook subscription that triggered this event
          example: 01234567-89ab-cdef-0123-456789abcdef
        event_type:
          type: string
          description: Event type identifier
          example: transfers#state-change
        sent_at:
          type: string
          format: date-time
          description: Timestamp when the event was sent
          example: '2020-01-01T12:34:56Z'
        data:
          type: object
          properties:
            resource:
              type: object
              properties:
                type:
                  type: string
                  description: Resource type
                  example: transfer
                id:
                  type: integer
                  format: int64
                  description: Transfer ID
                  example: 111
                profile_id:
                  type: integer
                  format: int64
                  description: Profile ID of the transfer owner
                  example: 222
                account_id:
                  type: integer
                  format: int64
                  description: Recipient account ID
                  example: 333
            current_state:
              type: string
              description: 'Current transfer status. See [Transfer Statuses](/guides/product/send-money/tracking-transfers) for possible values.

                '
              example: processing
            previous_state:
              type:
              - string
              - 'null'
              description: Previous transfer status. Note that this will be null for newly created transfers.
              example: incoming_payment_waiting
            occurred_at:
              type: string
              format: date-time
              description: Timestamp when the state change occurred
              example: '2020-01-01T12:34:56Z'
    v2.0.0-3:
      title: Schema version 2.0.0
      type: object
      properties:
        schema_version:
          type: string
          description: Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook).
          enum:
          - 2.0.0
          example: 2.0.0
        subscription_id:
          type: string
          format: uuid
          description: ID of the webhook subscription that triggered this event
          example: 36c3f762-560d-4f07-84f9-5d8a3cacabbb
        event_type:
          type: string
          description: Event type identifier
          example: account-details-payment#state-change
        sent_at:
          type: string
          format: date-time
          description: Timestamp when the event was sent
          example: '2024-01-01T12:34:56Z'
        data:
          type: object
          properties:
            resource:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
                  description: Balance ID which is linked to the account detail
                  example: 12345
                profile_id:
                  type: integer
                  format: int64
                  description: ID of the profile that owns the payment
                  example: 1
                type:
                  type: string
                  description: Type of the resource
                  example: balance-account
            account_details_id:
              type: string
              description: Account detail ID where the pay-in was received
              example: '1'
            target_account_id:
              type: string
              description: Balance ID which is linked to the account detail
              example: '12345'
            transfer:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
                  description: ID of the incoming transfer
                  example: 36454
                type:
                  type: string
                  description: Type of the transfer
                  example: credit
                amount:
                  type: number
                  format: decimal
                  description: Transfer amount
                  example: 120
                currency:
                  type: string
                  description: Currency code
                  example: EUR
            sender:
              type: object
              properties:
                name:
                  type: string
                  description: Sender name
                  example: Test Sender
                account_number:
                  type: string
                  description: Sender account number
                  example: '12345678'
                bank_code:
                  type: string
                  description: Sender bank code
                  example: TESTBANK
                address:
                  type: string
                  description: Sender address
                  example: Test Address
            current_state:
              type: string
              description: Current state of the payment
              enum:
              - PROCESSING
              - COMPLETED
              - CANCELLED
              - REFUNDED
              example: COMPLETED
            previous_state:
              type: string
              description: Previous state of the payment
              enum:
              - PROCESSING
              - COMPLETED
              - CANCELLED
              - REFUNDED
              example: PROCESSING
            occurred_at:
              type: string
              format: date-time
              description: Timestamp when the event occurred
              example: '2026-02-24T11:10:13Z'
    v2.0.0-2:
      title: Schema version 2.0.0
      type: object
      properties:
        schema_version:
          type: string
          description: Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook).
          enum:
          - 2.0.0
          example: 2.0.0
        subscription_id:
          type: string
          format: uuid
          description: ID of the webhook subscription that triggered this event
          example: 01234567-89ab-cdef-0123-456789abcdef
        event_type:
          type: string
          description: Event type identifier
          example: transfers#active-cases
        sent_at:
          type: string
          format: date-time
          description: Timestamp when the event was sent
          example: '2020-01-01T12:34:56Z'
        data:
          type: object
          properties:
            resource:
              type: object
              properties:
                type:
                  type: string
                  description: Resource type
                  example: transfer
                id:
                  type: integer
                  format: int64
                  description: Transfer ID
                  example: 111
                profile_id:
                  type: integer
                  format: int64
                  description: Profile ID of the transfer owner
                  example: 222
                account_id:
                  type: integer
                  format: int64
                  description: Recipient account ID
                  example: 333
            active_cases:
              type: array
              items:
                type: string
              description: Ongoing issues related to the transfer
              example:
              - deposit_amount_less_invoice
    v2.0.0-4:
      title: Schema version 2.0.0
      type: object
      properties:
        schema_version:
          type: string
          description: Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook).
          enum:
          - 2.0.0
          example: 2.0.0
        subscription_id:
          type: string
          format: uuid
          description: ID of the webhook subscription that triggered this event
          example: 5281e333-a4d9-4960-aec3-553267a9a8aa
        event_type:
          type: string
          description: Event type identifier
          example: cards#manual-provisioning-verification
        sent_at:
          type: string
          format: date-time
          description: Timestamp when the event was sent
          example: '2026-03-09T05:52:37Z'
        data:
          type: object
          properties:
            resource:
              type: object
              propertie

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wise/refs/heads/main/openapi/wise-webhook-event-api-openapi.yml