> For the complete documentation index, see [llms.txt](https://docs.vaultid.com.br/workspace/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vaultid.com.br/workspace/cess/hubdeautenticacao/eventos-e-mensagens.md).

# Eventos e Mensagens

Uma vez que o Hub foi aberto em modo Popup, toda a troca de informações entre o Hub e a sua aplicação é feita através da API nativa do navegador **postMessage**.

Sua aplicação deve registrar um ouvinte para o evento `message` do objeto `window`, filtrar pela origem correta e tratar os dados retornados.

{% hint style="info" icon="lightbulb-on" %}
**Fluxo Manual Automatizado Opcional**\
A captura do OTP via eventos Javascript é opcional e recomendada para uma integração fluida. Contudo, se seu fluxo for manual, o usuário pode simplesmente copiar o código OTP da tela do Hub e digitá-lo no formulário do seu site. Para este caso, não é obrigatório implementar os listeners de eventos.
{% endhint %}

{% hint style="success" %}
**Atenção ao Cadastro de Origem (Whitelist)**\
A Soluti verifica a URL de origem da aplicação antes de enviar a mensagem de sucesso ou erro. Caso sua aplicação esteja rodando em um domínio não cadastrado em nosso banco de dados, o Hub não enviará os eventos pós-autenticação.
{% endhint %}

#### Eventos Retornados

O Certifier Auth Hub dispara os seguintes eventos estruturados em formato JSON:

<table><thead><tr><th width="217">Tipo do Evento (type)</th><th width="202">Quando ocorre</th><th width="253">Parâmetros retornados</th></tr></thead><tbody><tr><td><mark style="color:violet;">signature_session_otp</mark></td><td>Autenticação concluída com sucesso e código OTP gerado.</td><td><p></p><ul><li><code>otp</code>: Código de uso único gerado.</li><li><code>cpf_cnpj</code>: Documento do titular do certificado.</li><li><code>session_id</code>: ID UUID da sessão.</li><li><code>certifier_id</code>: Código ID da certificadora.</li><li><code>certifier_name</code>: Nome amigável do provedor.</li><li><code>certifier_image</code>: URL do logotipo da certificadora.</li><li><code>expires_at</code>: Timestamp UNIX de expiração do OTP</li></ul></td></tr><tr><td><mark style="color:violet;">signature_session_error</mark></td><td>Falha ou erro técnico na autenticação.</td><td><p></p><ul><li><code>message</code>: Descrição amigável do erro ocorrido.</li></ul></td></tr><tr><td><mark style="color:violet;">signature_session_cancel</mark></td><td>O usuário cancelou ativamente a operação ou fechou o Hub.</td><td><p></p><ul><li><code>message</code>: Motivo do cancelamento (ex: popup fechado).</li></ul></td></tr></tbody></table>

#### Exemplo de Código Completo para Capturar Eventos

Veja a seguir como implementar o listener e filtrar com segurança a origem das mensagens recebidas para evitar ataques de injeção de mensagens:

```javascript
// Exemplo de captura de eventos do Certifier Auth Hub

// Domínio de produção oficial
const appUrl = 'https://certifierauthhub.vaultid.com.br';

window.addEventListener('message', (event) => {
  // 1. Filtrar eventos apenas do domínio oficial do Hub (exige whitelist prévia na Soluti)
  if (event.origin !== appUrl) {
    return;
  }

  const data = event.data;
  
  // 2. Verificar se o evento pertence à estrutura de dados do Hub
  if (data && data.type) {
    console.log(`[Hub Event] ${data.type}`, data);

    // Limpa o polling de fechamento do popup se ele ainda estiver ativo
    if (window.authPollTimer) {
      clearInterval(window.authPollTimer);
      window.authPollTimer = null;
    }

    switch (data.type) {
      case 'signature_session_otp':
        console.log('Sucesso! OTP Gerado:', data.otp);
        console.log('CPF/CNPJ do titular:', data.cpf_cnpj);
        console.log('ID da Sessão:', data.session_id);
        console.log('ID do Provedor:', data.certifier_id);
        console.log('Nome do Provedor:', data.certifier_name);
        console.log('Logotipo do Provedor:', data.certifier_image);
        console.log('Expiração do OTP (UNIX):', data.expires_at);
        
        // TODO: Enviar o OTP e o ID da sessão ao seu backend para assinar o documento
        
        // Fechar a janela do popup após o sucesso
        if (window.authPopupWindow && !window.authPopupWindow.closed) {
          window.authPopupWindow.close();
        }
        break;

      case 'signature_session_error':
        console.error('Ocorreu um erro no Hub:', data.message);
        alert(`Erro na autenticação: ${data.message}`);
        
        // Fechar a janela do popup devido à falha
        if (window.authPopupWindow && !window.authPopupWindow.closed) {
          window.authPopupWindow.close();
        }
        break;

      case 'signature_session_cancel':
        console.warn('Cancelado pelo usuário:', data.message);
        
        // Limpar referências do popup
        window.authPopupWindow = null;
        break;
    }
  }
});
```

{% hint style="info" icon="lightbulb-on" %}
**Dica de Segurança:** Em produção, certifique-se de validar a propriedade `event.origin` comparando-a estritamente com o domínio oficial de produção (`https://certifierauthhub.vaultid.com.br`), rejeitando mensagens de qualquer outra origem.
{% endhint %}