Eventos (SignatureEvent)

Trilha de auditoria do envelope. Cada linha registra uma coisa que aconteceu: envio, visualização, assinatura, recusa, falha de biometria.

É a tabela que responde por que um envelope está no estado em que está — sem ela, um contrato travado fica indefinidamente "em assinatura" e ninguém sabe se o cliente não abriu o e-mail, se a biometria reprovou ou se o provedor caiu.

Fato imutável

O evento nunca sofre update. Não tem log de auditoria, não vai para a lixeira, não é editado. Só INSERT e SELECT.

É a mesma regra das transações de conta: um registro que existe para provar o que aconteceu não pode ser reescrito depois, ou deixa de provar.

Correção não é edição — é um evento novo.

Recebimento de webhook

O provedor notifica cada mudança. O tratamento é:

1. Verificar a assinatura. O corpo vem acompanhado de um HMAC calculado com a chave do envelope (callbackToken). A QI Sign usa HMAC-SHA1 sobre endpoint + método + payload, no header Signature.
2. Checar idempotência. Se já existe evento com o mesmo externalEventId para a empresa, o webhook é descartado — provedores reenviam.
3. Gravar o evento, com o payload cru e verified dizendo se o HMAC conferiu.
4. Aplicar o efeito no envelope, no signatário e no requisito — apenas se verified = true.

Evento não verificado é gravado, mas não muda nada

Um webhook cuja assinatura não confere é registrado, com verified = false. Descartá-lo silenciosamente apagaria o rastro de uma possível tentativa de forjar conclusão de contrato.

O que ele não faz é alterar o estado do envelope.

Por que o payload cru é guardado

A documentação da QI Tech avisa explicitamente que os webhooks não devem ser mapeados de forma restrita, porque campos novos podem ser incluídos a qualquer momento.

Guardar o corpo original significa que um campo que a plataforma ainda não interpreta não se perde: ele fica disponível para diagnóstico e para um mapeamento futuro, sem exigir que o provedor reenvie nada.

Pelo mesmo motivo, a desserialização é tolerante: campo desconhecido nunca derruba o processamento.

Campos

Identificação e vínculo

Campo	Tipo	Para que serve
id	string (uuid)	Identificador do evento, e chave primária da tabela. O evento não tem nid: é fato imutável, nunca é referenciado por outro registro e nasce com UUID v7, que já ordena por tempo.
signatureNid	integer	nid do envelope.
signerNid	integer	nid do signatário, quando o evento é de uma pessoa específica. 0 para evento do envelope.
documentNid	integer	nid do documento, quando o evento é de um arquivo específico. 0 caso contrário. A Clicksign dispara eventos por documento, não por envelope.

Classificação

Campo	Tipo	Para que serve
eventType	object (code/key/name)	O que aconteceu, no vocabulário canônico. Ver SignatureEventType. Inválido → 1006028.
source	object (code/key/name)	Como soubemos: ação interna, webhook ou consulta ativa. Ver SignatureEventSource. Inválido → 1006029.
description	string | null	Descrição legível, quando o provedor manda uma ("USUÁRIO ACESSOU LINK DE ASSINATURA"). É o que aparece na trilha em tela.

Tempo

Campo	Tipo	Para que serve
occurredAt	string (date-time)	Quando o fato aconteceu, segundo o provedor.
receivedAt	string (date-time)	Quando a notificação chegou até nós.

Os dois existem separados porque webhooks atrasam e chegam fora de ordem. occurredAt ordena a história; receivedAt explica por que a plataforma demorou a reagir.

Provedor

Campo	Tipo	Para que serve
externalEventId	string | null	Id do evento no provedor. Chave de idempotência: impede que um reenvio conte duas vezes.
externalEventType	string | null	Nome do evento no vocabulário do provedor (envelope_completed, laas.credit_operation.status_change). Além de auditoria, é o campo que decide qual mapper interpreta o corpo.
externalCode	integer	Código numérico de retorno do provedor (returnCode da Confia).
externalStatus	string | null	Status cru associado ao evento.

Dois webhooks para o mesmo fato

A QI Tech notifica conclusão de assinatura por dois caminhos diferentes: envelope_completed, do QI Sign puro, e laas.credit_operation.status_change, da esteira de crédito.

Os dois trazem biometria, com nomes de campo diferentes para o mesmo dado, e correlacionam por chaves diferentes — um pelo id do envelope, outro pela operação de crédito. É externalEventType que decide qual tradução aplicar, e é o par feature + parentNid do envelope que resolve a correlação no segundo caso.

Evidência

Campo	Tipo	Para que serve
ipAddress	string | null	IP de onde partiu a ação.
latitude	decimal | null	Latitude no momento do evento.
longitude	decimal | null	Longitude. A Confia devolve as duas juntas em latLong dentro de cada item de auditoria.
verified	boolean	A assinatura HMAC do webhook conferiu. false significa origem não confirmada — o evento fica registrado, mas não altera o envelope.
payload	string | null	Corpo original da notificação, em JSON. Não é devolvido nas leituras normais; é dado de auditoria.