WebhookPayload

Estrutura padrão do payload de webhook enviado para clientes

  • data
    required

    Dados específicos do evento (estrutura varia conforme o tipo)

    Dados de webhook para eventos de transação

    • amount
      Type: integer

      Valor em centavos

    • companyId
      Type: string

      ID da empresa

    • createdAt
      Type: string Format: date-time

      Data de criação em horário de Brasília (America/Sao_Paulo), contrato ISO com sufixo Z

    • currency
      enum
      const:  
      BRL

      Moeda (sempre BRL)

      values
      • BRL
    • description
      Type: string nullable

      Descrição da transação

    • id
      Type: string

      ID da transação

    • installments
      Type: integer

      Número de parcelas

    • netTransactionAmount
      Type: integer

      Valor líquido em centavos (após taxas)

    • paidAt
      Type: string Format: date-timenullable

      Data de pagamento (ISO 8601)

    • paymentMethod
      Type: string enum

      Método de pagamento (UPPERCASE)

      values
      • PIX
      • CREDIT_CARD
      • BOLETO
    • status
      Type: string enum

      Status da transação (UPPERCASE)

      values
      • PENDING
      • PROCESSING
      • PAID
      • FAILED
      • CANCELED
      • BLOCKED
      • REFUNDED
      • PRE_CHARGEBACK
      • CHARGEBACK
  • event
    Type: string enum
    required

    Tipo do evento

    values
    • transaction.completed
    • transaction.failed
    • transaction.pending
    • transaction.refunded
    • withdrawal.completed
    • withdrawal.failed
    • withdrawal.canceled
  • eventId
    Type: string Pattern: ^(tx|wd):[^:]+:[A-Z_]+$|^resend:.+$|^evt_.+$
    required

    ID estável do evento de negócio para idempotência. Transação: tx:{transactionId}:{STATUS} (ex. tx:cmxyz:PENDING). Saque: wd:{withdrawalId}:{STATUS}. Reenvio em lote: resend:{entityId}:{STATUS}:{batchId}. Entregas antigas podem usar o formato legado evt_....

  • signature
    Type: string
    required

    Assinatura HMAC-SHA256 do payload (futuro - atualmente vazio)

  • source
    Type: string
    required

    Origem do webhook

  • timestamp
    Type: string Format: date-time
    required

    Timestamp do evento em ISO 8601

  • version
    Type: string
    required

    Versão do formato do webhook

  • retryCount
    Type: integer
    min:  
    0
    max:  
    5

    Número de tentativas de envio (apenas em retries)