# 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

```http
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)

```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.