Moov Webhooks

asyncapi: 2.6.0
info:
  title: Moov Webhooks
  description: >-
    Moov delivers real-time event notifications to your application via webhooks
    when state changes occur on your platform. When an event occurs, Moov sends
    an HTTP POST request with a JSON payload to your configured endpoint URL.
    Each delivery includes cryptographic headers for signature verification using
    HMAC-SHA512. Webhooks can be configured for all event types or scoped to
    specific events such as transfer status changes, account updates, and dispute
    notifications. Configure webhook endpoints in the Moov Dashboard under
    Developers > Webhooks.
  version: '2026.01.00'
  contact:
    name: Moov Support
    url: https://docs.moov.io/guides/webhooks/
externalDocs:
  description: Moov Webhook Documentation
  url: https://docs.moov.io/guides/webhooks/
servers:
  yourEndpoint:
    url: 'https://your-server.example.com/webhooks'
    protocol: https
    description: >-
      Your HTTPS webhook endpoint. Moov requires HTTPS for all webhook URLs.
      Configure this URL in the Moov Dashboard under Developers > Webhooks.
    security:
      - hmacSignature: []
channels:
  /webhook:
    description: >-
      Moov sends all webhook events as HTTP POST requests to your registered
      endpoint URL. Each request contains a JSON payload with the event type,
      data, and metadata, plus cryptographic headers for signature verification.
    publish:
      operationId: receiveMoovWebhookEvent
      summary: Receive a Moov webhook event
      description: >-
        Handle incoming webhook events from Moov. Verify the HMAC-SHA512 signature
        using the X-Signature header before processing the event payload. Concatenate
        the X-Timestamp, X-Nonce, and X-Webhook-ID header values with pipe delimiters
        and hash them with your signing secret to validate authenticity.
      message:
        oneOf:
          - $ref: '#/components/messages/AccountCreated'
          - $ref: '#/components/messages/AccountUpdated'
          - $ref: '#/components/messages/AccountDeleted'
          - $ref: '#/components/messages/RepresentativeCreated'
          - $ref: '#/components/messages/RepresentativeUpdated'
          - $ref: '#/components/messages/RepresentativeDisabled'
          - $ref: '#/components/messages/CapabilityRequested'
          - $ref: '#/components/messages/CapabilityUpdated'
          - $ref: '#/components/messages/BankAccountCreated'
          - $ref: '#/components/messages/BankAccountUpdated'
          - $ref: '#/components/messages/BankAccountDeleted'
          - $ref: '#/components/messages/PaymentMethodEnabled'
          - $ref: '#/components/messages/PaymentMethodDisabled'
          - $ref: '#/components/messages/TransferCreated'
          - $ref: '#/components/messages/TransferUpdated'
          - $ref: '#/components/messages/RefundCreated'
          - $ref: '#/components/messages/RefundUpdated'
          - $ref: '#/components/messages/SweepCreated'
          - $ref: '#/components/messages/SweepUpdated'
          - $ref: '#/components/messages/DisputeCreated'
          - $ref: '#/components/messages/DisputeUpdated'
          - $ref: '#/components/messages/BalanceUpdated'
          - $ref: '#/components/messages/WalletTransactionUpdated'
          - $ref: '#/components/messages/BillingStatementCreated'
          - $ref: '#/components/messages/InvoiceCreated'
          - $ref: '#/components/messages/InvoiceUpdated'
components:
  securitySchemes:
    hmacSignature:
      type: httpApiKey
      name: X-Signature
      in: header
      description: >-
        HMAC-SHA512 signature for verifying webhook authenticity. To validate:
        1. Extract X-Timestamp, X-Nonce, and X-Webhook-ID headers.
        2. Concatenate them as "timestamp|nonce|webhookID".
        3. Compute HMAC-SHA512 using your signing secret from the Moov Dashboard.
        4. Compare the result to the X-Signature header value.
        Discard the event if signatures do not match.
  messages:
    AccountCreated:
      name: account.created
      title: Account Created
      summary: A new Moov account was created.
      description: >-
        Fired when a new account is created on your platform. Use this event to
        trigger onboarding flows, capability requests, or record-keeping in your
        system.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/AccountEventPayload'
    AccountUpdated:
      name: account.updated
      title: Account Updated
      summary: An existing Moov account was updated.
      description: >-
        Fired when account profile data, verification status, or metadata changes.
        Use this to sync account state in your system and react to verification
        status changes.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/AccountEventPayload'
    AccountDeleted:
      name: account.deleted
      title: Account Deleted
      summary: A Moov account was deleted.
      description: >-
        Fired when an account is removed from the platform. Use this to clean up
        associated data in your application.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/AccountEventPayload'
    RepresentativeCreated:
      name: representative.created
      title: Representative Created
      summary: A business representative was added to an account.
      description: >-
        Fired when a new business representative is associated with a Moov
        business account for KYB compliance.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/RepresentativeEventPayload'
    RepresentativeUpdated:
      name: representative.updated
      title: Representative Updated
      summary: A business representative's information was updated.
      description: >-
        Fired when a representative's profile, responsibilities, or verification
        status changes on a business account.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/RepresentativeEventPayload'
    RepresentativeDisabled:
      name: representative.disabled
      title: Representative Disabled
      summary: A business representative was disabled on an account.
      description: >-
        Fired when a representative is removed or disabled from a Moov business
        account.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/RepresentativeEventPayload'
    CapabilityRequested:
      name: capability.requested
      title: Capability Requested
      summary: A capability was requested for a Moov account.
      description: >-
        Fired when a new capability is requested on an account, indicating that
        Moov is evaluating eligibility and may require additional information.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/CapabilityEventPayload'
    CapabilityUpdated:
      name: capability.updated
      title: Capability Updated
      summary: The status of a capability changed.
      description: >-
        Fired when a capability transitions between states (e.g., from pending to
        enabled, or when new requirements are added). Use this to prompt users to
        complete onboarding steps.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/CapabilityEventPayload'
    BankAccountCreated:
      name: bankAccount.created
      title: Bank Account Created
      summary: A bank account was linked to a Moov account.
      description: >-
        Fired when a new bank account is connected to a Moov account as a funding
        source. The bank account may still need verification before it can be
        used for transfers.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/BankAccountEventPayload'
    BankAccountUpdated:
      name: bankAccount.updated
      title: Bank Account Updated
      summary: A linked bank account was updated.
      description: >-
        Fired when the status or details of a linked bank account change, including
        when verification completes or fails.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/BankAccountEventPayload'
    BankAccountDeleted:
      name: bankAccount.deleted
      title: Bank Account Deleted
      summary: A bank account was removed from a Moov account.
      description: >-
        Fired when a bank account is unlinked and deleted from a Moov account.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/BankAccountEventPayload'
    PaymentMethodEnabled:
      name: paymentMethod.enabled
      title: Payment Method Enabled
      summary: A payment method became available for use.
      description: >-
        Fired when a payment method (bank account, card, or wallet) is enabled
        and available for use as a transfer source or destination on an account.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/PaymentMethodEventPayload'
    PaymentMethodDisabled:
      name: paymentMethod.disabled
      title: Payment Method Disabled
      summary: A payment method was disabled.
      description: >-
        Fired when a payment method is disabled and can no longer be used for
        new transfers on an account.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/PaymentMethodEventPayload'
    TransferCreated:
      name: transfer.created
      title: Transfer Created
      summary: A new transfer was initiated.
      description: >-
        Fired when a new money movement transfer is created on the platform.
        This is the initial event in the transfer lifecycle. Subscribe to
        transfer.updated for ongoing status changes.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/TransferEventPayload'
    TransferUpdated:
      name: transfer.updated
      title: Transfer Updated
      summary: A transfer's status or details changed.
      description: >-
        Fired as a transfer progresses through its lifecycle. Moov sends both
        overall transfer status updates and granular, rail-specific status updates
        to provide full visibility into each stage of the money movement process.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/TransferEventPayload'
    RefundCreated:
      name: refund.created
      title: Refund Created
      summary: A refund was created for a card transfer.
      description: >-
        Fired when a refund is initiated against a completed card transfer. The
        refund may be full or partial.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/RefundEventPayload'
    RefundUpdated:
      name: refund.updated
      title: Refund Updated
      summary: A refund's status changed.
      description: >-
        Fired when a refund progresses through its lifecycle, including when
        it completes or fails.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/RefundEventPayload'
    SweepCreated:
      name: sweep.created
      title: Sweep Created
      summary: A new sweep execution was created.
      description: >-
        Fired when a scheduled sweep transfer is created based on an active
        sweep configuration. The sweep will transfer available wallet funds
        to the configured bank account.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/SweepEventPayload'
    SweepUpdated:
      name: sweep.updated
      title: Sweep Updated
      summary: A sweep execution's status changed.
      description: >-
        Fired when the status of a sweep execution changes, such as when the
        underlying transfer completes or fails.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/SweepEventPayload'
    DisputeCreated:
      name: dispute.created
      title: Dispute Created
      summary: A card payment dispute was opened.
      description: >-
        Fired when a cardholder initiates a dispute (chargeback) against a card
        payment on your platform. Review the dispute details and submit evidence
        by the respondBy deadline to contest it.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/DisputeEventPayload'
    DisputeUpdated:
      name: dispute.updated
      title: Dispute Updated
      summary: A dispute's status or phase changed.
      description: >-
        Fired when a dispute progresses through its lifecycle, including when
        evidence is reviewed, when the dispute moves to arbitration, or when
        it is resolved as won or lost.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/DisputeEventPayload'
    BalanceUpdated:
      name: balance.updated
      title: Balance Updated
      summary: A Moov wallet balance was updated.
      description: >-
        Fired when the available balance of a Moov wallet changes due to a
        transfer, refund, sweep, fee, or other wallet transaction.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/BalanceEventPayload'
    WalletTransactionUpdated:
      name: walletTransaction.updated
      title: Wallet Transaction Updated
      summary: A wallet transaction's status changed.
      description: >-
        Fired when a wallet transaction status changes, providing granular
        visibility into individual credits and debits within a wallet.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/WalletTransactionEventPayload'
    BillingStatementCreated:
      name: billingStatement.created
      title: Billing Statement Created
      summary: A merchant billing statement became available.
      description: >-
        Fired when a new billing statement is generated and available for download
        in the Moov Dashboard. Billing statements summarize fees and transactions
        for the billing period.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/BillingStatementEventPayload'
    InvoiceCreated:
      name: invoice.created
      title: Invoice Created
      summary: A new invoice was created.
      description: >-
        Fired when a new invoice is generated on the platform.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/InvoiceEventPayload'
    InvoiceUpdated:
      name: invoice.updated
      title: Invoice Updated
      summary: An invoice was updated.
      description: >-
        Fired when an existing invoice is updated, such as when its status changes
        or payment is applied.
      headers:
        $ref: '#/components/schemas/WebhookHeaders'
      payload:
        $ref: '#/components/schemas/InvoiceEventPayload'
  schemas:
    WebhookHeaders:
      type: object
      description: HTTP headers included with every Moov webhook delivery for security verification.
      properties:
        X-Timestamp:
          type: string
          description: ISO 8601 timestamp of when the webhook was sent. Used in signature verification.
        X-Nonce:
          type: string
          description: One-time random value used in signature verification to prevent replay attacks.
        X-Webhook-ID:
          type: string
          description: Unique identifier for this webhook delivery attempt.
        X-Signature:
          type: string
          description: >-
            HMAC-SHA512 hash of the concatenated string "timestamp|nonce|webhookID"
            signed with the webhook signing secret from the Moov Dashboard.
    WebhookEventBase:
      type: object
      description: Base structure shared by all Moov webhook event payloads.
      required:
        - eventID
        - type
        - createdOn
      properties:
        eventID:
          type: string
          format: uuid
          description: Unique identifier for this event instance.
        type:
          type: string
          description: Event type identifier describing what occurred (e.g., "transfer.created").
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the event was generated.
        data:
          type: object
          description: Event-specific payload data relevant to what occurred.
    AccountEventPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          properties:
            data:
              type: object
              description: Account event data.
              properties:
                accountID:
                  type: string
                  format: uuid
                  description: Unique identifier of the affected account.
                accountType:
                  type: string
                  description: Whether the account is for an individual or a business.
                  enum: [individual, business]
                displayName:
                  type: string
                  description: Human-readable display name for the account.
                verificationStatus:
                  type: string
                  description: Current KYC/KYB verification status of the account.
                  enum: [unverified, pending, resubmit, review, verified, failed]
                createdOn:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp when the account was created.
                updatedOn:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp when the account was last updated.
    RepresentativeEventPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          properties:
            data:
              type: object
              description: Representative event data.
              properties:
                accountID:
                  type: string
                  format: uuid
                  description: The account this representative is associated with.
                representativeID:
                  type: string
                  format: uuid
                  description: Unique identifier for the representative.
                createdOn:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp when the representative was created.
                updatedOn:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp when the representative was last updated.
                disabledOn:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp when the representative was disabled, if applicable.
    CapabilityEventPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          properties:
            data:
              type: object
              description: Capability event data.
              properties:
                accountID:
                  type: string
                  format: uuid
                  description: The account this capability is associated with.
                capability:
                  type: string
                  description: Identifier of the capability type.
                status:
                  type: string
                  description: New status of the capability after the event.
                  enum: [enabled, disabled, pending, in-review]
                requirements:
                  type: array
                  description: Outstanding requirements needed to activate the capability.
                  items:
                    type: object
                    properties:
                      requirement:
                        type: string
                        description: Identifier of the outstanding requirement.
                      errorCode:
                        type: string
                        description: Error code providing detail about the requirement.
                updatedOn:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp when the capability was updated.
    BankAccountEventPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          properties:
            data:
              type: object
              description: Bank account event data.
              properties:
                accountID:
                  type: string
                  format: uuid
                  description: The Moov account this bank account belongs to.
                bankAccountID:
                  type: string
                  format: uuid
                  description: Unique identifier for the bank account.
                bankName:
                  type: string
                  description: Name of the financial institution.
                bankAccountType:
                  type: string
                  description: Type of bank account.
                  enum: [checking, savings, loan]
                status:
                  type: string
                  description: Updated status of the bank account.
                  enum: [new, unverified, pending, verified, errored]
                verificationStatus:
                  type: string
                  description: Updated verification status of the bank account.
                  enum: [unverified, pending, verificationFailed, verified, mxVerified]
                updatedOn:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp when the bank account was updated.
    PaymentMethodEventPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          properties:
            data:
              type: object
              description: Payment method event data.
              properties:
                accountID:
                  type: string
                  format: uuid
                  description: The account this payment method belongs to.
                paymentMethodID:
                  type: string
                  format: uuid
                  description: Unique identifier for the payment method.
                paymentMethodType:
                  type: string
                  description: Type of the payment method.
                  enum: [moov-wallet, ach-debit-fund, ach-debit-collect, ach-credit-standard, ach-credit-same-day, rtp-credit, card-payment]
                updatedOn:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp when the payment method status changed.
    TransferEventPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          properties:
            data:
              type: object
              description: Transfer event data.
              properties:
                transferID:
                  type: string
                  format: uuid
                  description: Unique identifier for the transfer.
                accountID:
                  type: string
                  format: uuid
                  description: The platform account associated with the transfer.
                status:
                  type: string
                  description: Current lifecycle status of the transfer.
                  enum: [created, pending, completed, failed, reversed]
                amount:
                  type: object
                  description: Transfer amount.
                  properties:
                    currency:
                      type: string
                      description: ISO 4217 currency code.
                    value:
                      type: integer
                      description: Amount in the smallest currency unit.
                createdOn:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp when the transfer was created.
                updatedOn:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp when the transfer was last updated.
                completedOn:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp when the transfer completed.
    RefundEventPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          properties:
            data:
              type: object
              description: Refund event data.
              properties:
                refundID:
                  type: string
                  format: uuid
                  description: Unique identifier for the refund.
                transferID:
                  type: string
                  format: uuid
                  description: The transfer this refund is associated with.
                accountID:
                  type: string
                  format: uuid
                  description: The account associated with the refund.
                status:
                  type: string
                  description: Current status of the refund.
                  enum: [created, pending, completed, failed]
                amount:
                  type: object
                  description: Refund amount.
                  properties:
                    currency:
                      type: string
                      description: ISO 4217 currency code.
                    value:
                      type: integer
                      description: Amount in the smallest currency unit.
                updatedOn:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp when the refund was last updated.
    SweepEventPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          properties:
            data:
              type: object
              description: Sweep event data.
              properties:
                sweepID:
                  type: string
                  format: uuid
                  description: Unique identifier for the sweep execution.
                sweepConfigID:
                  type: string
                  format: uuid
                  description: The sweep configuration that triggered this sweep.
                accountID:
                  type: string
                  format: uuid
                  description: The account associated with the sweep.
                walletID:
                  type: string
                  format: uuid
                  description: The wallet from which funds were swept.
                transferID:
                  type: string
                  format: uuid
                  description: The transfer created to execute the sweep.
                status:
                  type: string
                  description: Execution status of the sweep.
                  enum: [scheduled, pending, completed, failed]
                amount:
                  type: object
                  description: Amount swept.
                  properties:
                    currency:
                      type: string
                      description: ISO 4217 currency code.
                    value:
                      type: integer
                      description: Amount in the smallest currency unit.
                createdOn:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp when the sweep was created.
    DisputeEventPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          properties:
            data:
              type: object
              description: Dispute event data.
              properties:
                disputeID:
                  type: string
                  format: uuid
                  description: Unique identifier for the dispute.
                transferID:
                  type: string
                  format: uuid
                  description: The transfer associated with this dispute.
                accountID:
                  type: string
                  format: uuid
                  description: The account associated with the dispute.
                phase:
                  type: string
                  description: Current phase of the dispute lifecycle.
                  enum: [new, pre-arbitration, arbitration, won, lost]
                status:
                  type: string
                  description: Current status of the dispute.
                  enum: [new, responded, under-review, waiting-for-customer, closed]
                amount:
                  type: object
                  description: Disputed amount.
                  properties:
                    currency:
                      type: string
                      description: ISO 4217 currency code.
                    value:
                      type: integer
                      description: Amount in the smallest currency unit.
                respondBy:
                  type: string
                  format: date-time
                  description: ISO 8601 deadline for submitting evidence.
                updatedOn:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp when the dispute was updated.
    BalanceEventPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          properties:
            data:
              type: object
              description: Balance updated event data.
              properties:
                accountID:
                  type: string
                  format: uuid
                  description: The account whose wallet balance changed.
                walletID:
                  type: string
                  format: uuid
                  description: The wallet whose balance was updated.
                availableBalance:
                  type: object
                  description: Updated available balance of the wallet.
                  properties:
                    currency:
                      type: string
                      description: ISO 4217 currency code.
                    value:
                      type: integer
                      description: Balance amount in the smallest currency unit.
                updatedOn:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp when the balance was updated.
    WalletTransactionEventPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookEventBase'
        - type: object
          properties:
            data:
              type: object
              description: Wallet transaction event data.
              properties:
                accountID:
                  type: string
                  format: uuid
                  description: The account associated with the wallet transaction.
                walletID:
                  type: string
                  format: uuid
                  description: The wallet this transaction belongs to.
                transactionID:
                  type: string
                  format: uuid
                  description: Unique identifier for the wallet transaction.
                transactionType:
             

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/moov/refs/heads/main/asyncapi/moov-webhooks-asyncapi.yml