JSON Web Token (JWT)

Guia de Segurança para Webhooks da Facesign (com uso de JWT)

Introdução

Esta seção descreve o mecanismo de segurança adotado pela Facesign para envio de webhooks, com base na tecnologia JWT (JSON Web Token). O uso do JWT permite garantir a autenticidade das mensagens enviadas, preservar a integridade dos dados e mitigar riscos como falsificação e reutilização de requisições (replay attacks).

---

Motivação para o uso de JWT

Webhooks são utilizados pela Facesign para notificar sistemas integrados sobre eventos relevantes (por exemplo, a assinatura de um documento). Para assegurar que essas notificações:

• Sejam provenientes da Facesign,

• Não tenham sido alteradas durante o trânsito,

• Não sejam reutilizadas de forma indevida,

é adicionado um token JWT assinado a cada webhook enviado.

---

Conceito de JWT

O JWT (JSON Web Token) é um padrão de token assinado digitalmente que contém informações relevantes sobre o evento enviado. Ele é composto por três partes:

• Header: metadados sobre o tipo do token e algoritmo utilizado.

• Payload: dados do evento, como timestamps, tipo de evento, identificadores.

• Signature: assinatura digital que garante a integridade do conteúdo.

Esse token funciona como um envelope lacrado: qualquer tentativa de alteração em seu conteúdo invalida a assinatura.

---

Funcionamento do processo

Emissão do webhook pela Facesign

1. A Facesign gera um JWT contendo os dados do evento.

2. O JWT é assinado com uma chave segura.

3. O webhook é enviado via requisição HTTP, com o JWT incluso no cabeçalho da requisição.

Processamento e validação no sistema receptor

1. O sistema receptor extrai o JWT da requisição recebida.

2. O token é validado quanto à origem, assinatura e validade temporal.

3. Os dados do evento são processados conforme a necessidade da aplicação.

---

Exemplo de webhook enviado

POST /seu-endpoint HTTP/1.1
Host: suaempresa.com
Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

{
  "event": "document.signed",
  "data": {
    "documentId": "abc123",
    "signedAt": "2025-04-17T12:00:00Z"
  }
}

Exemplo de validação do JWT (em Python)

import jwt

# Chave secreta fornecida pela Facesign
FACESIGN_SECRET = "sua_chave_secreta_facesign"

# Token recebido
token = "<JWT_RECEBIDO_NO_HEADER>"

try:
    payload = jwt.decode(token, FACESIGN_SECRET, algorithms=["HS256"], audience="suaempresa.com")
    print("Webhook válido:", payload)
except jwt.ExpiredSignatureError:
    print("Erro: Token expirado.")
except jwt.InvalidTokenError:
    print("Erro: Token inválido.")

Elementos que devem ser validados no token

• iss: Confirma que o token foi emitido pela Facesign.

• aud: Garante que o token é destinado à aplicação correta.

• iat e exp: Verificam a validade temporal do token.

• jti: Identificador único do token, útil para evitar reprocessamento de mensagens.

Recomendações de segurança

• Utilização de HTTPS: O endpoint de recebimento de webhooks deve operar obrigatoriamente sob HTTPS, garantindo a proteção dos dados em trânsito.

• Expiração de tokens: Os tokens emitidos possuem tempo de validade reduzido. É essencial que a verificação de expiração seja implementada.

• Mitigação de replay attacks: Recomenda-se armazenar temporariamente os valores de jti dos tokens já processados, de forma a evitar a execução repetida de um mesmo evento.

• Proteção da chave secreta: A chave utilizada para verificação da assinatura JWT deve ser armazenada de forma segura, sem exposição pública ou em repositórios versionados.