Webhooks de Onboarding

Todos os eventos de onboarding seguem o envelope padrão de webhooks da plataforma (mesmo formato de entrega, autenticação, retries e idempotência). Esta página documenta os eventos específicos de accreditation.

Eventos

Evento	Quando é emitido
accreditation.pf.created	Uma accreditation PF foi criada.
accreditation.pj.created	Uma accreditation PJ foi criada.
accreditation.biometry.link.created	Um link de captura facial foi gerado para uma pessoa (emitido por pessoa; reemitido em retry).
accreditation.acceptance.link.created	Um link de aceite foi gerado para uma pessoa (somente fluxo de biometria própria).
accreditation.consent.link.created	Um link de autorização foi gerado porque o CPF já tem conta (reemitido em retry).
account.shared_access.granted	Outro tenant passou a operar uma conta que você já operava, autorizado pelo titular.
accreditation.updated	Toda transição de estado da accreditation. Fonte de verdade do progresso.
accreditation.active	Conta aberta com sucesso — accountId pronto para operar.
accreditation.failed	Processo encerrado sem abertura de conta.

Recomendação

Assine accreditation.updated como fonte de verdade do progresso, e use accreditation.active / accreditation.failed como gatilhos terminais no seu sistema. Os eventos de link servem para automatizar a entrega dos links aos usuários finais.

O callbackUri não substitui estes eventos

Se você usa o retorno ao seu app, o outcome que chega na URI é uma dica de interface: ele viaja na barra de endereço e o próprio titular pode editá-lo. Use-o só para escolher que tela mostrar quando o usuário voltar. Todo gatilho com efeito no seu sistema continua vindo daqui — ou de GET /v1/accreditations/{accreditationId}.

accreditation.updated

Emitido em toda transição de estado, com o status anterior, o atual e o detalhe por pessoa.

{
  "id": "evt_acr_upd_001",
  "type": "accreditation.updated",
  "occurredAt": "2026-07-07T18:20:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "document": "12345678901",
    "previousStatus": "PENDING_BIOMETRY",
    "status": "INTEGRATING",
    "persons": [
      {
        "cpf": "12345678901",
        "name": "Maria da Silva",
        "biometryStatus": "APPROVED"
      }
    ]
  }
}

Campo do data	Descrição
accreditationId	ID da accreditation.
type	pf ou pj.
document	CPF (PF) ou CNPJ (PJ) do titular.
previousStatus / status	Transição de estado (vocabulário da Visão Geral).
persons[]	Detalhe por pessoa: cpf, name, biometryStatus (PENDING, APPROVED, FAILED, EXPIRED) e, no fluxo BYO, acceptanceStatus (PENDING, ACCEPTED).
errorReason	Presente quando status = FAILED.

accreditation.biometry.link.created

Emitido quando um link de captura facial é gerado para uma pessoa (na criação da accreditation e em cada retry).

{
  "id": "evt_acr_link_001",
  "type": "accreditation.biometry.link.created",
  "occurredAt": "2026-07-07T18:00:05.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "biometryLink": "https://cadastro.unico.app/process/abc123...",
    "linkExpiresAt": "2026-07-14T18:00:00Z"
  }
}

No PJ, este evento é emitido uma vez por sócio — use o cpf para saber a quem entregar cada link.

accreditation.acceptance.link.created

Somente no fluxo de biometria própria. Emitido quando o link de aceite é gerado para uma pessoa.

{
  "id": "evt_acr_acc_001",
  "type": "accreditation.acceptance.link.created",
  "occurredAt": "2026-07-07T18:05:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "acceptanceLink": "https://tenant.api.corpx.com/v1/accreditations/accept/tok_...",
    "linkExpiresAt": "2026-07-14T18:00:00Z"
  }
}

accreditation.consent.link.created

Emitido quando o CPF informado já tem conta e a accreditation nasce em PENDING_CONSENT: em vez de abrir conta nova, o titular precisa autorizar que você opere a conta existente. Entregue o consentLink a ele. Reemitido a cada retry.

{
  "id": "acr-acr_5c4b3a2f1e0d-consent-12345678901-1",
  "type": "accreditation.consent.link.created",
  "occurredAt": "2026-07-23T18:00:05.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "data": {
    "accreditationId": "acr_5c4b3a2f1e0d",
    "type": "pf",
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "consentId": "cns_8f2a1c9d4b70",
    "consentLink": "https://tenant.api.corpx.com/v1/accreditations/consent/cst_...",
    "linkExpiresAt": "2026-07-30T18:00:00Z",
    "status": "PENDING_CONSENT"
  }
}

Detalhes da jornada em Titular que já tem conta.

accreditation.active

Evento terminal de sucesso — a conta está pronta para operar.

{
  "id": "evt_acr_active_001",
  "type": "accreditation.active",
  "occurredAt": "2026-07-07T18:25:41.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "document": "12345678901",
    "status": "ACTIVE",
    "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8"
  }
}

Quando a accreditation veio do fluxo de consent, o data traz dois campos adicionais:

Campo do data	Descrição
sharedAccount	true — a conta já existia e continua sendo operada por quem o titular já havia autorizado. Saldo e extrato são compartilhados.
partnerAccountId	Identificador do titular no liquidante, comum a todos os tenants autorizados. Útil para reconciliação.

account.shared_access.granted

Emitido para os tenants que já operavam uma conta quando o titular autoriza um novo tenant a operá-la também. O seu acesso não muda — este evento existe para você saber que a conta passou a ser movimentada por mais alguém.

{
  "id": "acr-acr_5c4b3a2f1e0d-shared-tenant-acme",
  "type": "account.shared_access.granted",
  "occurredAt": "2026-07-23T18:40:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
    "tenantId": "tenant-acme",
    "partnerAccountId": "hld_7c1e...",
    "grantedAt": "2026-07-23T18:40:00Z",
    "reason": "account_holder_authorized_another_tenant"
  }
}

Campo do data	Descrição
accountId	A sua conta (o identificador que você já usa), não a do tenant que entrou.
partnerAccountId	Titular no liquidante — é o que evidencia que se trata da mesma conta.
grantedAt	Momento da autorização do titular.
reason	account_holder_authorized_another_tenant.

Não reconheceu?

Se o compartilhamento não faz sentido para o seu caso, acione o suporte: o titular pode revogar o acesso concedido, e a partir da revogação as chamadas do tenant revogado para aquela conta respondem 403.

accreditation.failed

Evento terminal de falha — o processo foi encerrado sem abertura de conta.

{
  "id": "evt_acr_failed_001",
  "type": "accreditation.failed",
  "occurredAt": "2026-07-08T10:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "document": "12345678901",
    "status": "FAILED",
    "errorReason": "biometry_expired",
    "errorMessage": "Biometria facial não concluída dentro do prazo de 7 dias"
  }
}

Valores comuns de errorReason:

errorReason	Significado
biometry_failed	Biometria facial reprovada.
biometry_expired	Link de facial expirou sem conclusão.
evidence_invalid	Evidência de biometria própria não validada no parceiro (fluxo BYO).
acceptance_timeout	Termo de aceite não confirmado dentro do prazo (fluxo BYO).
cancelled	Cancelada pelo integrador via POST /v1/accreditations/{id}/cancel (ainda em PENDING_BIOMETRY ou PENDING_CONSENT).
review_rejected	Rejeitada na análise prévia.
partner_rejected	Rejeitada pelo liquidante na abertura da conta.
consent_declined	O titular recusou autorizar o acesso à conta que já tinha.
consent_expired	O titular não concluiu a autorização no prazo (link de 7 dias, jornada de 30 dias).
consent_facial_failed	A verificação de identidade não confirmou que a pessoa é a titular do CPF.
consent_link_failed	Não foi possível preparar ou concluir a autorização (ex.: dados do titular divergentes entre o pedido e a autorização). Acione o suporte.
castle_deny	A análise de dispositivo barrou o aceite — tanto no termo do fluxo BYO quanto na autorização de portabilidade. Acione o suporte.
existing_partner_account	CPF/CNPJ que já tem conta. A portabilidade é manual: o titular deve solicitá-la ao suporte. Em PF, se o seu tenant tiver a portabilidade automática habilitada, este motivo não ocorre — o caminho é o consentLink. Para PJ não existe fluxo de autorização em página.

accreditation.pf.created / accreditation.pj.created

Emitidos na criação da accreditation (início do workflow), como confirmação assíncrona do POST. Assine-os no portal (Settings → Webhooks) ou via PUT na subscription.

{
  "id": "acr-acr_1a2b3c4d5e6f-created",
  "type": "accreditation.pj.created",
  "occurredAt": "2026-07-07T18:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "data": {
    "accreditationId": "acr_1a2b3c4d5e6f",
    "type": "pj",
    "document": "12345678000199",
    "status": "PENDING_BIOMETRY",
    "biometryMode": "external"
  }
}