Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Eventos

Esta página descreve os diferentes eventos que podem acionar notificações de webhook na API Connect.

Estrutura do evento

Os webhooks da Certta seguem a CloudEvents especificação para a JSON estrutura do evento, um padrão da CNCF para descrever dados de eventos de forma comum. Esse formato padronizado facilita a integração com seus sistemas e garante consistência entre diferentes fontes de eventos. Observe que, embora o corpo siga o formato CloudEvents, os HTTP cabeçalhos do CloudEvents não estão incluídos na solicitação.

Cada evento de webhook segue esta estrutura compatível com CloudEvents:

{
  "specversion": "1.0",
  "type": "COMMUNICATIONCREATEDEVENT",
  "source": "COMMUNICATION",
  "id": "01JZNK5ZQBNF623MB5KE64GNQB",
  "time": "2025-07-08T18:01:19.622Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d",
    "channel": "sms",
    "externalId": "external-id",
    "notificationId": "01JZNK51YCZXT55TKF8M366QHJ",
    "system": "onboarding",
    "occurredOn": "2025-07-08T18:00:46.797Z"
  }
}
Campo
Descrição

id

Identificador único do evento

source

URI que indica onde o evento se originou

specversion

Versão da especificação CloudEvents (atualmente 1.0)

Tipo

Tipo do evento (veja os Tipos de evento abaixo)

time

Carimbo de data/hora em que o evento ocorreu (formato ISO 8601)

datacontenttype

Tipo de mídia do valor de dados (normalmente application/json)

data

Objeto contendo dados específicos do evento

Tipos de evento

O Connect atualmente oferece suporte aos seguintes tipos de evento:

Comunicação

Tipo de evento
Descrição

COMMUNICATIONCREATEDEVENT

Uma nova comunicação foi criada

COMMUNICATIONDELIVEREDEVENT

Uma comunicação foi entregue ao destinatário

COMMUNICATIONREJECTEDEVENT

Uma comunicação foi rejeitada

COMMUNICATIONNOTDELIVEREDEVENT

Uma comunicação não foi entregue ao destinatário

COMMUNICATIONSENTTODESTINATIONEVENT

Uma comunicação foi enviada ao seu destino

Transação

Tipo de evento
Descrição

TRANSACTIONPROCESSSTARTEDEVENT

Uma transação criada pelo Web Onboarding começou a ser processada depois que o usuário concluiu o fluxo de onboarding

TRANSACTIONSTATUSUPDATEDEVENT

O status de uma transação foi atualizado

TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT

Foi feita uma solicitação de cópia de documentos em uma transação

TRANSACTIONPROCESSSTARTEDEVENT é específico para transações iniciadas após um usuário concluir um fluxo de Web Onboarding. Não é um evento genérico de criação de transação e não é emitido quando uma transação é criada diretamente pela Transactions API.

SmartAuth

Tipo de evento
Descrição

FACEAUTHENTICATIONEVENT

Ocorreu uma tentativa de autenticação facial

PROFILEUPDATEDEVENT

O status de um perfil foi atualizado

Diretrizes de tratamento de eventos

Práticas recomendadas para consumidores de eventos

  1. Validação do tipo de evento: Sempre valide o tipo de evento antes de processar.

  2. Tratamento de erros: Implemente um tratamento de erros robusto para eventos malformados.

  3. Processamento idempotente: Processe eventos de forma idempotente usando o evento id para evitar processamento duplicado.

  4. Verificações de presença de campos: Não presuma que todos os campos estarão sempre presentes no payload do evento.

  5. Ordem dos eventos: Não conte com eventos chegando em ordem cronológica.

Futuros tipos de evento

A Certta está expandindo continuamente suas ofertas de eventos. Consulte a documentação regularmente para ver atualizações sobre tipos de evento recém-suportados. Se você precisar de eventos para mudanças de estado específicas que não estejam disponíveis no momento, entre em contato com o suporte da Certta.

A Certta pode adicionar novos campos a tipos de evento existentes sem considerar isso uma mudança incompatível. Portanto, o processamento dos seus eventos deve ser projetado para lidar com campos adicionais com facilidade.

Exemplos de eventos

Exemplos de eventos de comunicação

COMMUNICATIONCREATEDEVENT

COMMUNICATIONREJECTEDEVENT

COMMUNICATIONSENTTODESTINATIONEVENT

COMMUNICATIONDELIVEREDEVENT

COMMUNICATIONNOTDELIVEREDEVENT

Campos de dados comuns em eventos de comunicação

Todos os eventos de comunicação incluem estes campos comuns no data objeto:

Alguns eventos podem incluir campos adicionais:

Campo
Descrição

reason

Motivo da rejeição ou falha (em eventos REJECTED/NOTDELIVERED)

Campo
Descrição

tenantId

Identificador do tenant associado à comunicação

channel

Canal de comunicação (por exemplo, "sms", "email", "whatsapp")

externalId

Identificador externo da comunicação

notificationId

Identificador único da notificação

system

Sistema que originou a comunicação

occurredOn

Carimbo de data/hora em que o evento ocorreu

Tratamento de eventos de comunicação

Ao processar eventos de comunicação, considere as seguintes práticas recomendadas:

Ciclo de vida do evento de comunicação

As comunicações normalmente seguem esta sequência de eventos:

  1. COMMUNICATIONCREATEDEVENT - Criação inicial

  2. COMMUNICATIONSENTTODESTINATIONEVENT - Enviado ao provedor de entrega

  3. Um dos seguintes:

    • COMMUNICATIONDELIVEREDEVENT - Entregue com sucesso

    • COMMUNICATIONNOTDELIVEREDEVENT - Falha na entrega

    • COMMUNICATIONREJECTEDEVENT - Rejeitado antes do envio

Sua aplicação deve estar preparada para lidar com esses eventos em qualquer ordem, já que as atualizações de status de entrega nem sempre chegam em sequência.

Recomendações de tratamento de eventos

  • Sempre verifique o evento Tipo antes de processá-lo para garantir a lógica correta de tratamento

  • Armazene os status de comunicação usando tanto o notificationId e externalId para correlação

  • Implemente o tratamento idempotente de eventos para evitar problemas caso receba eventos duplicados

  • Preste atenção especial a COMMUNICATIONREJECTEDEVENT e COMMUNICATIONNOTDELIVEREDEVENT pois eles podem exigir ações de acompanhamento em seu sistema

Eventos de transação

Os eventos de transação fornecem atualizações em tempo real sobre o status e o ciclo de vida das transações no seu sistema.

Exemplos de eventos de transação

TRANSACTIONPROCESSSTARTEDEVENT

TRANSACTIONSTATUSUPDATEDEVENT

TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT

Campos de dados comuns em eventos de transação

Os eventos de transação usam os seguintes campos no data objeto. Os campos descritos como opcionais são omitidos quando não se aplicam:

Campo
Descrição

tenantId

Identificador do tenant associado à transação

report

Identificador do relatório para compatibilidade com o fluxo legado. Quando não houver relatório disponível, o valor é 000000000000000000000000

id

Identificador único da transação

status

Status de negócio atual da transação. Veja os valores de status da transação abaixo

data

Carimbo de data/hora em que o evento ocorreu

onboardingId

Identificador do processo de onboarding que gerou a transação. Presente apenas para transações originadas do Web Onboarding

templateId

Identificador do modelo de consulta usado para esta transação, quando disponível

customStatus

Status personalizado opcional definido pelo lojista e configurado no Trust. Omitido quando nenhum status personalizado se aplica

Valores de status da transação

O status o campo representa o resultado de negócio ou o estado de processamento da transação. Ele não representa o ciclo de vida do evento de webhook.

Valor
Descrição

PROCESSING

A transação ainda está sendo processada e seus dados podem mudar

APPROVED

A transação passou nas regras de validação configuradas

REPROVED

A transação contém uma irregularidade ou evidência de fraude

PENDING

A transação requer uma decisão ou ação manual no Trust

PENDING_OCR

O documento ou seus dados não puderam ser identificados automaticamente e requerem ação manual

O evento Tipo descreve o que aconteceu, enquanto data.status descreve o status de negócio atual da transação. Por exemplo, um TRANSACTIONPROCESSSTARTEDEVENT ou TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT pode conter status: "PROCESSING".

Valores de status personalizados

customStatus é opcional e não possui uma lista global de valores. Seus possíveis valores são definidos pela configuração do fluxo de trabalho de cada lojista no Trust. Portanto, as integrações devem tratá-lo como uma string específica do tenant e não devem assumir que os valores usados por um tenant estejam disponíveis para outro tenant.

Quando nenhum status definido pelo lojista se aplica, customStatus é omitido do evento. Use status para o estado padrão da transação no Connect e customStatus apenas para o mapeamento específico do tenant.

Os motivos detalhados da validação não estão incluídos nos payloads dos eventos de transação. Use GET /transactions/{transactionId} com data.id para recuperar os detalhes completos da transação.

Tratamento de eventos de transação

Ao processar eventos de transação, considere as seguintes práticas recomendadas:

Ciclo de vida do evento de transação

As transações originadas do Web Onboarding normalmente seguem esta sequência:

  1. POST /onboardings retorna um link de onboarding. Não existe transação e nenhum evento de transação é emitido neste ponto.

  2. TRANSACTIONPROCESSSTARTEDEVENT - O usuário concluiu o fluxo de onboarding e a transação resultante começou a ser processada.

  3. TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT - Documentos são solicitados para processamento (se aplicável).

  4. TRANSACTIONSTATUSUPDATEDEVENT - O status muda à medida que o processamento avança.

    • Pode ser emitido várias vezes à medida que a transação passa por várias etapas

Transações criadas diretamente pela API de Transactions não emitem TRANSACTIONPROCESSSTARTEDEVENT. Sua aplicação deve usar o identificador da transação retornado na solicitação de criação e acompanhar os TRANSACTIONSTATUSUPDATEDEVENT eventos.

Em qualquer dos fluxos, os eventos de transação relevantes devem estar habilitados na seleção de eventos do webhook no Trust.

O elemento de nível superior do CloudEvents id identifica o evento de webhook. O data.id campo identifica a transação e deve ser usado para correlacionar eventos de transação.

Eventos do SmartAuth

Os eventos do SmartAuth fornecem informações sobre tentativas de autenticação e atualizações de perfil.

Exemplos de eventos do SmartAuth

FACEAUTHENTICATIONEVENT

PROFILEUPDATEDEVENT

Campos de dados em eventos do SmartAuth

Campos do FACEAUTHENTICATIONEVENT:

Campos do PROFILEUPDATEDEVENT:

Campo
Descrição

tenantId

Identificador do tenant associado ao perfil

profileId

Identificador único do perfil

Tipo

Tipo de perfil (PF para pessoa física, PJ para empresa)

status

Status atual do perfil

updatedAt

Carimbo de data/hora em que o perfil foi atualizado

cpf

Identificador de CPF brasileiro (quando aplicável)

cnpj

Identificador de CNPJ brasileiro (quando aplicável)

Campo
Descrição

tenantId

Identificador do tenant associado à autenticação

onboardingId

Identificador do processo de onboarding associado

personId

Identificador da pessoa que está sendo autenticada

attemptId

Identificador único desta tentativa de autenticação

isMatch

Booleano indicando se a autenticação facial foi bem-sucedida

data

Carimbo de data/hora em que a autenticação ocorreu

Tratamento de eventos do SmartAuth

Ao processar eventos do SmartAuth, considere as seguintes práticas recomendadas:

Tratamento de eventos do SmartAuth

Para FACEAUTHENTICATIONEVENT:

  • Verifique o isMatch campo para determinar se a autenticação foi bem-sucedida

  • Use o personId para correlacionar com seus registros de usuário

  • Considere implementar medidas de segurança adicionais para tentativas de autenticação malsucedidas

Para PROFILEUPDATEDEVENT:

  • Atualize seus registros locais de usuário com o status mais recente do perfil

  • Tome as ações apropriadas com base nas mudanças de status (por exemplo, habilitar/desabilitar recursos)

  • Armazene tanto profileId quanto os identificadores de documento (cpf/cnpj) para correlação

Atualizado