> 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/connect/webhook/events.md). # Eventos Esta página descreve os diferentes eventos que podem acionar notificações de webhook na API Connect. ## Estrutura do evento {% hint style="info" %} Os webhooks da Certta seguem a [CloudEvents](https://cloudevents.io/) 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. {% 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 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 | {% hint style="warning" %} `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. {% endhint %} ### 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 {% hint style="info" %} ### 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. {% endhint %} ## 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. {% hint style="warning" %} 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. {% 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": "Telefone do destinatário fora de alcance" } } ``` {% hint style="info" %} ### 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: {% endhint %} | 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: {% 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, já que 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 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 {% 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" } } ``` {% hint style="info" %} ### 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: {% endhint %} | 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 | {% 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 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: {% 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. 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. {% 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 em eventos do SmartAuth **Campos do FACEAUTHENTICATIONEVENT:** **Campos do PROFILEUPDATEDEVENT:** {% endhint %} | 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: {% hint style="success" %} **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 {% 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.caf.io/caf-api/caf-api-pt-br/connect/webhook/events.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.