Referência de Webhooks

Referência de payloads de webhook (catálogo de eventos por domínio). Conteúdo migrado de documentation/finaya-webhooks.md. Para o guia de uso, ver Webhooks (Jornada); para a visão geral de eventos e lacunas conhecidas, ver Eventos & Webhooks — Visão Geral.

Diagrama do Fluxo

Esta página é um catálogo de eventos e payloads por domínio. O diagrama abaixo resume os domínios de evento documentados (FATO) e a entrega ao integrador. A configuração/assinatura de webhook é feita pela API de Webhooks. [INFERÊNCIA] sobre o canal de entrega; mecanismo de retry/reenvio não está documentado.

Mapeamento de Eventos e Payloads

Abaixo está a lista de todos os domínios, os eventos associados e a estrutura do JSON que você receberá nos eventos do webhook.

Domínio: PIX

Eventos: PIX_CREATED, PIX_UPDATED -> Criação e atualização de transferências Pix

{
  "event_id": "96364930bbb9082eec5ea16946750e8a04b21d5bb6255160ce5a30b9dee9e9e5",
  "type": "PIX_UPDATED|PIX_CREATED",
  "query_params": null,
  "path_params": null,
  "data":{
  "id": "string",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "account_id": "string",
  "amount": 0,
  "idempotency_key": "string",
  "internal_transaction_id": "string",
  "end_to_end_id": "string",
  "metadata": [{"key": "string", "value": "string"}],
  "receiver_account_number": "string",
  "receiver_account_type": "string",
  "receiver_bank_code": "string",
  "receiver_branch_code": "string",
  "receiver_pix_key": "string",
  "receiver_name": "string",
  "receiver_tax_id": "string",
  "sender_account_number": "string",
  "sender_account_type": "string",
  "senderBankCode": "string",
  "senderBranchCode": "string",
  "sender_name": "string",
  "sender_tax_id": "string",
  "reconciliation_id": "string",
  "method": "string",
  "cash_amount": 0,
  "cashier_bank_code": "string",
  "cashier_type": "string",
  "description": "string",
  "type": "string",
  "txid": "string",
  "status": "string",
  "control_cash_in_txid": "string",
  "external_id": "pix-out-1"
}

Eventos: PIX_REVERSAL_CREATED, PIX_REVERSAL_UPDATED -> Criação e atualização de devoluções

{
  "event_id": "f9c94ed39efd5d8e2d919223fb7fd7938beebf19e36c0a96a708a2c802d204fd",
  "type": "PIX_REVERSAL_UPDATED",
  "query_params": null,
  "path_params": null,
  "account_id": "string",
  "data": {
    "accountId": "string",
    "amount": 100,
    "endToEndId": "string",
    "reason": "string",
    "returnId": "string",
    "txId": "string",
    "pixType": "PIX_OUT",
    "status": "SUCCESS",
    "id": "string",
    "created_at": "2026-01-29T03:00:36.51500",
    "updated_at": "2026-01-29T03:00:40.95002"
  }
}

Eventos: PIX_KEY_CREATED, PIX_KEY_UPDATED -> Criação e atualização de chaves Pix

{
  "event_id": "96364930bbb9082eec5ea16946750e8a04b21d5bb6255160ce5a30b9dee9e9e5",
  "type": "PIX_KEY_CREATED|PIX_KEY_UPDATED",
  "query_params": null,
  "path_params": null,
  "data":{
  "id": "string",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "personId": "string",
  "accountId": "string",
  "key": "string",
  "metadata": [{"key": "string", "value": "string"}],
  "status": "string",
  "type": "string"
}
}

Eventos: PIX_LIMIT_CREATED, PIX_LIMIT_UPDATED -> Criação e atualização de limite Pix

{
  "event_id": "96364930bbb9082eec5ea16946750e8a04b21d5bb6255160ce5a30b9dee9e9e5",
  "type": "PIX_LIMIT_CREATED|PIX_LIMIT_UPDATED",
  "query_params": null,
  "path_params": null,
  "data":{
  "id": "string",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "account_id": "string",
  "type": "string",
  "period": "string",
  "amount": 0,
  "max_amount": 0
}
}

Eventos: PIX_KEY_CLAIM_CREATED, PIX_KEY_CLAIM_UPDATED -> Criação e atualização de portabilidade e reinvidicação

{
  "event_id": "string",
  "type": "PIX_KEY_CLAIM_CREATED|PIX_KEY_CLAIM_UPDATED",
  "query_params": null,
  "path_params": null,
  "data":{
  "id": "string",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "20-10-27T10:00:00.000Z",
  "internal_id": "string",
  "person_id": "string",
  "account_id": "string",
  "key": "string",
  "key_type": "string",
  "status": "string",
  "flow": "string",
  "request_date": "yyyy-MM-dd'T'HH:mm:ss.SSSSS",
  "expiration_date": "yyyy-MM-dd'T'HH:mm:ss.SSSSS",
  "completion_date": "yyyy-MM-dd'T'HH:mm:ss.SSSSS",
  "rejection_reason": "string",
  "account_created": "string",
  "account_number": "string",
  "account_type": "string",
  "branch_code": "string",
  "claimed_bank_code": "string",
  "claimer_bank_code": "string",
  "name": "string",
  "document": "string",
  "type": "string"
}
}

Evento: PIX_SCHEDULE_UPDATED -> Atualização de agendamento Pix

{
  "event_id": "string",
  "type": "PIX_SCHEDULE_UPDATED",
  "query_params": null,
  "path_params": null,
  "data":{
  "id": "string",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "account_id": "string",
  "amount": 0,
  "schedule_date": "yyyy-MM-dd",
  "metadata": [{"key": "string", "value": "string"}],
  "receiver_account_number": "string",
  "receiver_account_type": "string",
  "receiver_bank_code": "string",
  "receiver_branch_code": "string",
  "receiver_pix_key": "string",
  "receiver_name": "string",
  "receiver_tax_id": "string",
  "reconciliation_id": "string",
  "sender_account_number": "string",
  "sender_account_type": "string",
  "sender_bank_code": "string",
  "sender_branch_code": "string",
  "sender_name": "string",
  "sender_tax_id": "string",
  "method": "string",
  "description": "string",
  "recurrence": "string",
  "status": "string",
  "recurrence_end_date": "yyyy-MM-dd"
}
}

Eventos: PIX_CHARGEBACK_CREATED, PIX_CHARGEBACK_UPDATED -> Criação e atualização de Chargeback

{
  "event_id": "string",
  "type": "PIX_CHARGEBACK_CREATED|PIX_CHARGEBACK_UPDATED",
  "query_params": null,
  "path_params": null,
  "data": {
    "id": "string",
    "created_at": "2023-10-27T10:00:00.000Z",
    "updated_at": "2023-10-27T10:00:00.000Z",
    "amount": 0,
    "reference_id": "string",
    "description": "string",
    "reason": "string",
    "status": "string",
    "external_id": "string",
    "result": "string",
    "reject_reason": "string",
    "reversal_reference_id": "string",
    "analysis": "string",
    "flow": "string"
  }
}

Eventos: PIX_INFRACTION_CREATED, PIX_INFRACTION_UPDATED -> Criação e atualização de infrações

{
  "event_id": "string",
  "type": "PIX_INFRACTION_CREATED|PIX_INFRACTION_UPDATED",
  "query_params": null,
  "path_params": null,
  "data": {
    "id": "string",
    "created_at": "2023-10-27T10:00:00.000Z",
    "updated_at": "2023-10-27T10:00:00.000Z",
    "reference_id": "string",
    "type": "string",
    "method": "string",
    "description": "string",
    "operator_email": "string",
    "operator_phone": "string",
    "status": "string",
    "external_id": "string",
    "fraud_type": "string",
    "analysis": "string",
    "result": "string",
    "flow": "string"
  }
}

Eventos: PIX_LIMIT_REQUEST_CREATED, PIX_LIMIT_REQUEST_UPDATED -> Solicitação de alteração de limite Pix

{
  "event_id": "string",
  "type": "PIX_LIMIT_REQUEST_CREATED|PIX_LIMIT_REQUEST_UPDATED",
  "query_params": null,
  "path_params": null,
  "data":{
  "id": "string",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "account_id": "string",
  "type": "string",
  "period": "string",
  "current_value": 0,
  "requested_value": 0,
  "status": "string",
  "reason": "string",
  "processed_at": "yyyy-MM-dd'T'HH:mm:ss",
  "processed_by": "string"
}
}

Domínio: Charge

Evento: PIX_CHARGE_BACEN_UPDATED -> Confirmação de pagamento de QR Code Dinâmico

{
  "pix": [
    {
      "endToEndId": "E1823...",
      "txid": "a20e5...",
      "valor": "1.00",
      "horario": "2026-02-07T15:45:15.947",
      "devolucoes": [],
      "pagador": {
        "numeroConta": "111111",
        "tipoConta": "",
        "ispb": "111111",
        "agencia": "0001",
        "nome": "Pagador",
        "documento": "111..."
      },
      "recebedor": {
        "numeroConta": "22222",
        "tipoConta": "",
        "ispb": "22222",
        "agencia": "0001",
        "nome": "Recebedor",
        "documento": "222..."
      },
      "idExterno": "order-1",
      "metadados": {
        "produto": "123"
      },
      "idReconciliacao": "olh67oc...."
    }
  ],
  "id": "8a9e9573-6965-482b-a687-c03ebc0f433a",
  "created_at": "2026-02-07T15:45:15.94716",
  "updated_at": "2026-02-07T15:45:15.94716",
  "partner_organization_id": null
}

Domínio: Account Holder

Evento: ACCOUNT_HOLDER_CREATED

{
  "event_id": "string",
  "type": "ACCOUNT_HOLDER_CREATED",
  "query_params": null,
  "path_params": null,
  "data":{
  "id": "string",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "document": "string",
  "additional_information": {
    "key": "string"
  }
}
}

Domínio: Transaction

Evento: TRANSACTION_EVENT_CREATED

{
  "event_id": "string",
  "type": "TRANSACTION_EVENT_CREATED",
  "query_params": null,
  "path_params": null,
  "data":{
  "id": "string",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "tx_id": "string",
  "previous_tx": "string",
  "account_id": "string",
  "source": "string",
  "destination": "string",
  "amount": 0,
  "transaction_type": "string",
  "metadata": [{"key": "string", "value": "string"}],
  "idempotency_key": "string",
  "merchant_category_code": "string",
  "internal_transaction_id": "string",
  "balance": 0
}
}

Evento: TRANSACTION_PROCESS_ERROR

{
  "event_id": "string",
  "type": "TRANSACTION_PROCESS_ERROR",
  "query_params": null,
  "path_params": null,
  "data":{
  "id": "string",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "error": "string",
  "data": {
    "id": "string",
    "created_at": "2023-10-27T10:00:00.000Z",
    "updated_at": "2023-10-27T10:00:00.000Z",
    "tx_id": "string",
    "previous_tx": "string",
    "account_id": "string",
    "source": "string",
    "destination": "string",
    "amount": 0,
    "transaction_type": "string",
    "metadata": [{"key": "string", "value": "string"}],
    "idempotency_key": "string",
    "merchant_category_code": "string",
    "internal_transaction_id": "string",
    "balance": 0
  }
}
}

Domínio: Individual Person

Eventos: INDIVIDUAL_CREATED, INDIVIDUAL_UPDATED

{
  "event_id": "string",
  "type": "INDIVIDUAL_CREATED|INDIVIDUAL_UPDATED",
  "query_params": null,
  "path_params": null,
  "data":{
  "id": "string",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "document": "string",
  "mail": "string",
  "phone": "string",
  "metadata": [{"key": "string", "value": "string"}],
  "first_name": "string",
  "last_name": "string",
  "mother_name": "string",
  "gender": "string",
  "birth_date": "yyyy-MM-dd",
  "identity_document": {
    "number": "string",
    "dispatching_agency": "string",
    "state": "string",
    "issue_date": "yyyy-MM-dd"
  },
  "addresses": [
    {
      "city": "string",
      "neighborhood": "string",
      "number": "string",
      "state": "string",
      "street": "string",
      "complement": "string",
      "postal_code": "string",
      "status": "string"
    }
  ],
  "internal_person_id": "string"
}
}

Domínio: Company

Eventos: COMPANY_CREATED, COMPANY_UPDATED

{
  "event_id": "string",
  "type": "COMPANY_CREATED|COMPANY_UPDATED",
  "query_params": null,
  "path_params": null,
  "data":{
  "id": "string",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "document": "string",
  "mail": "string",
  "phone": "string",
  "metadata": [{"key": "string", "value": "string"}],
  "legal_name": "string",
  "trading_name": "string",
  "founding_date": "yyyy-MM-dd",
  "state_registration": "string",
  "main_activity": "string",
  "website": "string",
  "business_type": "string",
  "addresses": [
    {
      "city": "string",
      "neighborhood": "string",
      "number": "string",
      "state": "string",
      "street": "string",
      "complement": "string",
      "postal_code": "string",
      "status": "string"
    }
  ],
  "internal_person_id": "string"
}
}

Domínio: Account

Eventos: ACCOUNT_CREATED, ACCOUNT_ACTIVATED, ACCOUNT_INFO_UPDATED, ACCOUNT_CREATE_ERROR

{
  "event_id": "string",
  "type": "ACCOUNT_CREATED|ACCOUNT_ACTIVATED|ACCOUNT_INFO_UPDATED|ACCOUNT_CREATE_ERROR",
  "query_params": null,
  "path_params": null,
  "data":{
  "id": "string",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "product": {
    "id": "string",
    "created_at": "2023-10-27T10:00:00.000Z",
    "updated_at": "2023-10-27T10:00:00.000Z",
    "name": "string",
    "token": "string",
    "status": "string",
    "metadata": [{"key": "string", "value": "string"}]
  },
  "person": {
    "id": "string",
    "created_at": "2023-10-27T10:00:00.000Z",
    "updated_at": "2023-10-27T10:00:00.000Z",
    "document": "string",
    "mail": "string",
    "phone": "string",
    "metadata": [{"key": "string", "value": "string"}]
  },
  "type": "string",
  "status": "string",
  "internal_account_id": "string",
  "metadata": [{"key": "string", "value": "string"}],
  "provider_id": "string"
}
}

Evento: ACCOUNT_BALANCE_UPDATED

{
  "event_id": "string",
  "type": "ACCOUNT_BALANCE_UPDATED",
  "query_params": null,
  "path_params": null,
  "data":{
  "id": "string",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "product": {
    "id": "string",
    "created_at": "2023-10-27T10:00:00.000Z",
    "updated_at": "2023-10-27T10:00:00.000Z",
    "name": "string",
    "token": "string",
    "status": "string",
    "metadata": [{"key": "string", "value": "string"}]
  },
  "person": {
    "id": "string",
    "created_at": "2023-10-27T10:00:00.000Z",
    "updated_at": "2023-10-27T10:00:00.000Z",
    "document": "string",
    "mail": "string",
    "phone": "string",
    "metadata": [{"key": "string", "value": "string"}]
  },
  "type": "string",
  "status": "string",
  "internal_account_id": "string",
  "metadata": [{"key": "string", "value": "string"}],
  "provider_id": "string",
  "balance": 0,
  "limit": 0,
  "balance_date": "yyyy-MM-dd'T'HH:mm:ss.SSSSS"
}
}

Domínio: Product

Eventos: PRODUCT_CREATED, PRODUCT_UPDATED

{
  "event_id": "string",
  "type": "PRODUCT_CREATED|PRODUCT_UPDATED",
  "query_params": null,
  "path_params": null,
  "data":{
  "id": "string",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "status": "string",
  "name": "string",
  "description": "string",
  "type": "string",
  "currency_code": "string",
  "internal_product_id": "string",
  "metadata": [{"key": "string", "value": "string"}],
  "merchant_category_codes": ["string"]
}
}

Diagrama do Fluxo​

Mapeamento de Eventos e Payloads​

Domínio: PIX​

Domínio: Charge​

Domínio: Account Holder​

Domínio: Transaction​

Domínio: Individual Person​

Domínio: Company​

Domínio: Account​

Domínio: Product​