Catálogo de Webhooks

O Zoop BaaS notifica o marketplace de mudanças de estado via webhooks. Os webhooks estão presentes em diversos fluxo, mas nessa página eles estão consolidados para facilitar o entendimento.

Configurando os Webhooks

Para saber como configurar os Webhooks acesse os links abaixo:

Guia de Implementação
API Reference - Webhooks

Envelope comum

A maioria dos eventos chega em um envelope WebHookEvent:

{
  "id": "9e84cfe283af484d8e715db77446290e",
  "type": "onboarding.approved",
  "resource": "event",
  "payload": {
    "object": { }
  },
  "created_at": "2024-10-25T10:17:12+00:00",
  "updated_at": "2024-10-25T10:17:12+00:00",
  "uri": "/v1/marketplaces/{marketplaceId}/events/{eventId}"
}

Campo	Tipo	Descrição
`id`	string	Identificador único do evento
`type`	string	Tipo do evento (ex.: `onboarding.approved`)
`resource`	string	Sempre `event`
`payload.object`	object	Dados específicos do evento
`created_at` / `updated_at`	datetime	Timestamps do evento
`uri`	string	URI do recurso (`/v1/marketplaces/{marketplaceId}/events/{eventId}`)

⚠️ Exceção: os eventos de agenda de recebíveis (seção abaixo) usam um envelope diferente, com o payload aninhado em payload.object.

Eventos de credenciamento

Tipo	Descrição
`onboarding.waiting_required_documents`	Onboarding aguardando documentos obrigatórios
`onboarding.approved`	Onboarding aprovado
`onboarding.rejected`	Onboarding negado

onboarding.waiting_documents

Para mais informações sobre seu uso, acesse Webhooks de Credenciamento.

{
  "type": "onboarding.waiting_required_documents",
  "resource": "event",
  "payload": {
    "object": {
      "onboarding_id": "onboarding-1",
      "status": "WAITING_REQUIRED_DOCUMENTS",
      "external_reference_id": "uuid-gerado-pelo-marketplace"
    }
  }
}

onboarding.approved

Para mais informações sobre seu uso, acesse Webhooks de Credenciamento.

{
  "type": "onboarding.approved",
  "resource": "event",
  "payload": {
    "object": {
      "onboarding_id": "onboarding-1",
      "profile_id": "11111111-1111-4111-8111-111111111111",
      "status": "APPROVED",
      "accounts": [
        { "account_id": "8ac1f0d2-77b4-4e19-9d3a-1c2e4f5a6b70" }
      ],
      "external_reference_id": "uuid-gerado-pelo-marketplace"
    }
  }
}

onboarding.rejected

Para mais informações sobre seu uso, acesse Webhooks de Credenciamento.

{
  "type": "onboarding.rejected",
  "resource": "event",
  "payload": {
    "object": {
      "onboarding_id": "onboarding-1",
      "profile_id": "11111111-1111-4111-8111-111111111111",
      "status": "REJECTED",
      "retry": true,
      "decision_reasons": [
        { "reason": "INTERNAL_KYC_POLICY", "detail": "DOCUMENT_NOT_MATCH" }
      ],
      "external_reference_id": "uuid-gerado-pelo-marketplace"
    }
  }
}

Eventos de Profile

Tipo	Descrição
`profile.external_account_validation_failed`	Validação da conta externa falhou
`profile.external_account_validation_succeeded`	Validação da conta externa foi concluída

{
  "type": "profile.external_account_validation_failed",
  "resource": "event",
  "payload": {
    "object": {
      "onboarding_id": "onboarding-1",
      "profile_id": "85b00690-...",
      "status": "EXTERNAL_ACCOUNT_VALIDATION_FAILED",
      "bank_code": "341",
      "agency_number": "3000",
      "account_number": "600000",
      "retry": true,
      "decision_reasons": [
        { "reason": "...", "detail": "..." }
      ]
    }
  }
}

ℹ️ retry e decision_reasons aparecem apenas em profile.external_account_validation_failed

Eventos de funds out

Tipo	Descrição
`transfer.succeeded`	Transferência liquidada
`transfer.failed`	Transferência falhou
`transfer.reversed`	Transferência liquidada foi revertida

{
  "type": "transfer.succeeded",
  "resource": "event",
  "payload": {
    "object": {
      "transfer_id": "3f2a1c9e-8b4d-4f61-9a02-5c7d1e6b0a34",
      "profile_id": "85b00690-...",
      "kind": "FUNDS_OUT",
      "status": "SUCCEEDED",
      "amount": 12000,
      "source_account_id": "8ac1f0d2-77b4-4e19-9d3a-1c2e4f5a6b70",
      "destination": {
        "bank_code": "341",
        "agency_number": "3000",
        "account_number": "600000",
        "account_type": "CHECKING"
      },
      "created_at": "2026-10-14T12:00:00Z",
      "updated_at": "2026-10-14T12:00:04Z",
      "end_to_end_id": "E2E..."
    }
  }
}

Campos adicionais por status:

end_to_end_id — presente em succeeded e reversed

failure_reason — presente em failed

refunded_amount / refund_reason — presentes em reversed

Eventos de agenda de recebíveis (efeitos de contrato)

Evento	Momento	Significado
`receivable_unit.contract.settlement`	Diariamente, após as 19h30	Efeito de contrato associado ao seller, a ser liquidado no próximo dia útil (D+1)

ℹ️ Pré-requisito: o marketplace precisa utilizar a última versão do termo de aceite, na qual o seller faz o opt-in da própria agenda de recebíveis para o marketplace ao qual pertence.

ℹ️ Janela de envio: o processo roda diariamente a partir das 19h30 — horário-limite para recebimento dos efeitos de contrato da registradora. Após o fechamento, o Zoop BaaS identifica todos os efeitos a liquidar no dia seguinte e publica os eventos.

Envelope

{
  "id": "9e84cfe283af484d8e715db77446290e",
  "type": "receivable_unit.contract.settlement",
  "resource": "event",
  "payload": {
    "object": {
      "id": "1462208c-948d-4e2a-96f4-fb00644b522a",
      "seller": "6fbf7ec8fa7c4429a3b03eb85dd43364",
      "type": "lien_cession",
      "document_owner": "12345678901234",
      "amount": { "value": 2000, "type": "fixed" },
      "reference": { "id": "77b9579a-1ca2-45bc-8ed4-a71400f7883f" },
      "unit": {
        "id": "d6389d47-c656-423d-a799-eac812cc956e",
        "modality": "credit",
        "brand": "MasterCard",
        "settlement_date": "2024-10-26"
      },
      "created_at": "2024-10-25T07:13:36-03:00"
    }
  },
  "uri": "/v1/marketplaces/0162893710a6495e86542eeff192baa1/events/9e84cfe283af484d8e715db77446290e",
  "created_at": "2024-10-25T10:17:12+00:00",
  "updated_at": "2024-10-25T10:17:12+00:00"
}

Dicionário de dados

Estrutura base do evento

Campo	Tipo	Descrição	Formato
`id`	string	Identificador único do evento	Hexadecimal (32 posições)
`type`	string	Tipo do evento	`receivable_unit.contract.settlement`
`resource`	string	Origem do recurso	`event`
`payload`	object	Informações do efeito de contrato	Objeto JSON
`uri`	string	Endereço (URI) deste recurso	`/v1/marketplaces/{marketplaceId}/events/{eventId}`
`created_at`	datetime	Criação do evento	`YYYY-MM-DDThh:mm:ss.sssTZD`
`updated_at`	datetime	Última atualização do evento	`YYYY-MM-DDThh:mm:ss.sssTZD`

payload.object — detalhes do contrato

Campo	Tipo	Descrição	Formato
`id`	string	Identificador único do contrato	UUID
`seller`	string	Identificador único do seller	Hexadecimal (32 posições)
`type`	string	Tipo do contrato	`lien_cession` (cessão fiduciária) ou `definitive_cession` (cessão definitiva)
`document_owner`	string	Documento da instituição que aplicou o contrato	CNPJ/CPF
`amount.value`	int \| float	Valor do contrato	`fixed` → valor em centavos (int); `percent` → ponto flutuante
`amount.type`	string	Se o valor é fixo ou percentual	`fixed` ou `percent`
`reference.id`	string	Referência da registradora	UUID
`unit.id`	string	Identificador da unidade de recebível	UUID
`unit.modality`	string	Modalidade de pagamento	`credit` ou `debit`
`unit.brand`	string	Bandeira do cartão	`visa`, `mastercard`, `elo`, etc.
`unit.settlement_date`	date	Data de liquidação da unidade de recebível (D+1)	`YYYY-MM-DD`
`created_at`	datetime	Criação do contrato	`YYYY-MM-DDThh:mm:ss.sssTZD`

ℹ️ amount.value em centavos: com amount.type = "fixed", o valor 2000 representa R$ 20,00.

Para o racional completo e o fluxo de decisão, veja Recebíveis tomados por outras instituições (efeito de contrato D+1).

Boas práticas no receptor
✅ Responda 2xx rapidamente (antes de processar)
✅ Deduplicação pelo identificador do evento (id ou event_id, conforme o envelope — a entrega é at-least-once)
✅ Trate a possibilidade de eventos fora de ordem
ℹ️ A entrega tem retry com backoff exponencial do lado do Zoop BaaS. Garanta idempotência no receptor.