> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-api/caf-api-pt-br/conectar/webhook/events.md). # Eventos Esta página descreve os diferentes eventos que podem acionar notificações de webhook na Connect API. ## Estrutura do evento {% hint style="info" %} Os webhooks da Certta seguem a [CloudEvents](https://cloudevents.io/) especificação para a `JSON` estrutura de evento, um padrão da CNCF para descrever dados de eventos de maneira comum. Esse formato padronizado facilita a integração com seus sistemas e garante consistência entre diferentes origens de eventos. Observe que, embora o corpo siga o formato CloudEvents, os `HTTP` cabeçalhos do CloudEvents não estão incluídos na requisição. {% endhint %} Cada evento de webhook segue esta estrutura compatível com CloudEvents: ```json { "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 indicando de onde o evento se originou | | `specversion` | Versão da especificação CloudEvents (atualmente 1.0) | | `tipo` | Tipo do evento (veja Tipos de Evento abaixo) | | `time` | Carimbo de data e hora em que o evento ocorreu (formato ISO 8601) | | `datacontenttype` | Tipo de mídia do valor de dados (normalmente application/json) | | `dados` | 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 após o usuário concluir o fluxo de onboarding | | `TRANSACTIONSTATUSUPDATEDEVENT` | O status de uma transação foi atualizado | | `TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT` | Uma solicitação de cópia de documentos em uma transação foi feita | | `TRANSACTIONVERIFAIDOCSERROREVENT` | A análise do VerifAI Docs de uma transação falhou e os arquivos enviados não foram retidos. Emitido apenas para contas com retenção zero em erros do VerifAI Docs habilitada | {% hint style="warning" %} `TRANSACTIONPROCESSSTARTEDEVENT` é específico para transações iniciadas depois que um usuário conclui 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. {% endhint %} ### SmartAuth | Tipo de Evento | Descrição | | ------------------------- | -------------------------------------------- | | `FACEAUTHENTICATIONEVENT` | Uma tentativa de autenticação facial ocorreu | | `PROFILEUPDATEDEVENT` | O status de um perfil foi atualizado | ## Diretrizes de tratamento de eventos {% hint style="info" %} ### Melhores práticas 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 dependa de os eventos chegarem em ordem cronológica. {% endhint %} ## Tipos de evento futuros A Certta está expandindo continuamente suas ofertas de eventos. Consulte a documentação regularmente para atualizações sobre novos tipos de evento compatíveis. Se você precisar de eventos para mudanças de estado específicas que ainda não estejam disponíveis, entre em contato com o suporte da Certta. {% hint style="warning" %} A Certta pode adicionar novos campos aos tipos de evento existentes sem considerar isso uma mudança que quebre compatibilidade. Seu processamento de eventos deve ser projetado para lidar com campos adicionais de forma adequada. {% endhint %} ## Exemplos de eventos ### Exemplos de eventos de comunicação #### COMMUNICATIONCREATEDEVENT ```json { "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" } } ``` #### COMMUNICATIONREJECTEDEVENT ```json { "specversion": "1.0", "type": "COMMUNICATIONREJECTEDEVENT", "source": "COMMUNICATION", "id": "01JZNK5ZQBNF623MB5KE64GNQC", "time": "2025-07-08T18:02: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:02:46.797Z", "reason": "Formato de número de telefone inválido" } } ``` #### COMMUNICATIONSENTTODESTINATIONEVENT ```json { "specversion": "1.0", "type": "COMMUNICATIONSENTTODESTINATIONEVENT", "source": "COMMUNICATION", "id": "01JZNK5ZQBNF623MB5KE64GNQD", "time": "2025-07-08T18:03: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:03:46.797Z" } } ``` #### COMMUNICATIONDELIVEREDEVENT ```json { "specversion": "1.0", "type": "COMMUNICATIONDELIVEREDEVENT", "source": "COMMUNICATION", "id": "01JZNK5ZQBNF623MB5KE64GNQE", "time": "2025-07-08T18:04: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:04:46.797Z" } } ``` #### COMMUNICATIONNOTDELIVEREDEVENT ```json { "specversion": "1.0", "type": "COMMUNICATIONNOTDELIVEREDEVENT", "source": "COMMUNICATION", "id": "01JZNK5ZQBNF623MB5KE64GNQF", "time": "2025-07-08T18:05: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:05:46.797Z", "reason": "O telefone do destinatário está inacessível" } } ``` {% hint style="info" %} ### Campos de dados comuns em eventos de comunicação Todos os eventos de comunicação incluem estes campos comuns no `dados` objeto: | 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 e hora em que o evento ocorreu | Alguns eventos podem incluir campos adicionais: | Campo | Descrição | | ------------- | -------------------------------------------------------------- | | `reason` | Motivo da rejeição ou falha (em eventos REJECTED/NOTDELIVERED) | | {% endhint %} | | ### Tratamento de eventos de comunicação Ao processar eventos de comunicação, considere as seguintes boas práticas: {% hint style="success" %} **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, pois as atualizações de status de entrega nem sempre chegam em sequência. {% endhint %} {% hint style="warning" %} **Recomendações de tratamento de eventos** * Sempre verifique o evento `tipo` antes de processar para garantir a lógica de tratamento correta * 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 você receba eventos duplicados * Preste atenção especial a `COMMUNICATIONREJECTEDEVENT` e `COMMUNICATIONNOTDELIVEREDEVENT` pois estes podem exigir ações de acompanhamento no seu sistema {% endhint %} ## 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 ```json { "specversion": "1.0", "type": "TRANSACTIONPROCESSSTARTEDEVENT", "source": "TRANSACTION", "id": "01JZNL6XQBNF623MB5KE64GNQB", "time": "2025-07-08T19:01:19.622Z", "datacontenttype": "application/json", "data": { "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d", "report": "000000000000000000000000", "id": "01JZNL6XQBNF623MB5KE64GNQB", "status": "PROCESSING", "date": "2025-07-08T19:01:19.622Z", "onboardingId": "01JZNL6XQBNF623MB5KE64GNQC", "templateId": "document-ocr-basic" } } ``` #### TRANSACTIONSTATUSUPDATEDEVENT ```json { "specversion": "1.0", "type": "TRANSACTIONSTATUSUPDATEDEVENT", "source": "TRANSACTION", "id": "01JZNL6XQBNF623MB5KE64GNQD", "time": "2025-07-08T19:05:19.622Z", "datacontenttype": "application/json", "data": { "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d", "report": "000000000000000000000000", "id": "01JZNL6XQBNF623MB5KE64GNQB", "status": "APPROVED", "date": "2025-07-08T19:05:19.622Z", "onboardingId": "01JZNL6XQBNF623MB5KE64GNQC", "templateId": "document-ocr-basic", "customStatus": "LOW_RISK_APPROVED" } } ``` #### TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT ```json { "specversion": "1.0", "type": "TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT", "source": "TRANSACTION", "id": "01JZNL6XQBNF623MB5KE64GNQE", "time": "2025-07-08T19:03:19.622Z", "datacontenttype": "application/json", "data": { "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d", "report": "000000000000000000000000", "id": "01JZNL6XQBNF623MB5KE64GNQB", "status": "PROCESSING", "date": "2025-07-08T19:03:19.622Z", "onboardingId": "01JZNL6XQBNF623MB5KE64GNQC", "templateId": "document-ocr-basic" } } ``` #### TRANSACTIONVERIFAIDOCSERROREVENT ```json { "specversion": "1.0", "type": "TRANSACTIONVERIFAIDOCSERROREVENT", "source": "TRANSACTION", "id": "01JZNL6XQBNF623MB5KE64GNQF", "time": "2025-07-08T19:04:19.622Z", "datacontenttype": "application/json", "data": { "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d", "report": "000000000000000000000000", "id": "01JZNL6XQBNF623MB5KE64GNQB", "status": "PENDING", "date": "2025-07-08T19:04:19.622Z", "templateId": "document-ocr-basic" } } ``` {% hint style="warning" %} **Falha na análise do VerifAI Docs com retenção zero** `TRANSACTIONVERIFAIDOCSERROREVENT` é emitido apenas para contas com o recurso de retenção zero em erros do VerifAI Docs habilitado. Quando a análise do VerifAI Docs de uma transação falha, os arquivos enviados não são retidos e a análise não será reprocessada: crie uma nova transação se você quiser uma nova análise. * O evento é enviado **apenas uma vez por transação**. * `data.status` contém o status da transação no momento do envio (`PENDING`, `REPROVED` ou outro valor, de acordo com as validações configuradas no modelo de consulta). * O evento comunica a **decisão** de não reter os arquivos, não uma confirmação de que a exclusão já foi concluída. {% endhint %} {% hint style="info" %} ### Campos de dados comuns em eventos de transação Os eventos de transação usam os seguintes campos no `dados` objeto. 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 fluxos legados. Quando nenhum relatório está 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 e 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 merchant e configurado no Trust. Omitido quando nenhum status personalizado se aplica | | {% endhint %} | | ### Valores de status da transação O `status` 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 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 exigem ação manual | {% hint style="info" %} 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"`. {% endhint %} ### 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 de fluxo de trabalho de cada merchant no Trust. Portanto, as integrações devem tratá-lo como uma string específica do tenant e não devem presumir que valores usados por um tenant estejam disponíveis para outro tenant. Quando nenhum status definido pelo merchant se aplica, `customStatus` é omitido do evento. Use `status` para o estado padrão de transação do Connect e `customStatus` apenas para mapeamento específico do tenant. Motivos detalhados de validação não estão incluídos nos payloads de 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 boas práticas: {% hint style="success" %} **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. Nenhuma transação existe e nenhum evento de transação é emitido neste momento. 2. `TRANSACTIONPROCESSSTARTEDEVENT` - O usuário concluiu o fluxo de onboarding e a transação resultante começou a ser processada. 3. `TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT` - Os documentos são solicitados para processamento (se aplicável). 4. `TRANSACTIONSTATUSUPDATEDEVENT` - O status muda conforme o processamento avança. * Pode ser emitido várias vezes à medida que a transação passa por várias etapas 5. `TRANSACTIONVERIFAIDOCSERROREVENT` - A análise do VerifAI Docs falhou e os arquivos enviados não foram retidos (apenas para contas com retenção zero em erros do VerifAI Docs habilitada). Transações criadas diretamente pela Transactions API não emitem `TRANSACTIONPROCESSSTARTEDEVENT`. Sua aplicação deve usar o identificador da transação retornado pela solicitação de criação e acompanhar os subsequentes `TRANSACTIONSTATUSUPDATEDEVENT` eventos. Para qualquer um dos fluxos, os eventos de transação relevantes devem estar habilitados na seleção de eventos do webhook no Trust. O 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. {% endhint %} ## 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 ```json { "specversion": "1.0", "type": "FACEAUTHENTICATIONEVENT", "source": "SMARTAUTH", "id": "01JZNL6XQBNF623MB5KE64GNQF", "time": "2025-07-08T19:10:19.622Z", "datacontenttype": "application/json", "data": { "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d", "onboardingId": "01JZNL6XQBNF623MB5KE64GNQC", "personId": "01JZNL6XQBNF623MB5KE64GNQG", "attemptId": "01JZNL6XQBNF623MB5KE64GNQH", "isMatch": true, "date": "2025-07-08T19:10:19.622Z" } } ``` #### PROFILEUPDATEDEVENT ```json { "specversion": "1.0", "type": "PROFILEUPDATEDEVENT", "source": "SMARTAUTH", "id": "01JZNL6XQBNF623MB5KE64GNQI", "time": "2025-07-08T19:15:19.622Z", "datacontenttype": "application/json", "data": { "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d", "profileId": "01JZNL6XQBNF623MB5KE64GNQJ", "type": "PF", "status": "APPROVED", "updatedAt": "2025-07-08T19:15:19.622Z", "cpf": "12345678901", "cnpj": null } } ``` {% hint style="info" %} ### Campos de dados nos eventos do SmartAuth **Campos do FACEAUTHENTICATIONEVENT:** | 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 e hora em que a autenticação ocorreu | **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 e hora em que o perfil foi atualizado | | `cpf` | Identificador do CPF (Cadastro de Pessoas Físicas) brasileiro (quando aplicável) | | `cnpj` | Identificador do CNPJ brasileiro (quando aplicável) | | {% endhint %} | | ### Tratamento de eventos do SmartAuth Ao processar eventos do SmartAuth, considere as seguintes boas práticas: {% hint style="success" %} **Tratamento de eventos do SmartAuth** Para `FACEAUTHENTICATIONEVENT`: * Verifique o `isMatch` campo para determinar o sucesso da autenticação * Use o `personId` para correlacionar com os registros dos seus usuários * Considere implementar medidas adicionais de segurança para tentativas de autenticação fracassadas Para `PROFILEUPDATEDEVENT`: * Atualize seus registros locais de usuários 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 ambos `profileId` e identificadores de documento (`cpf`/`cnpj`) para correlação {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.caf.io/caf-api/caf-api-pt-br/conectar/webhook/events.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.