# JSON Web Token (JWT)

## Facesign Webhooks Security Guide (using JWT)

### Introduction

This section describes the security mechanism adopted by Facesign for sending webhooks, based on the **JWT (JSON Web Token)**. The use of JWT ensures the authenticity of sent messages, preserves data integrity, and mitigates risks such as forgery and request reuse (replay attacks).

***

### Motivation for using JWT

Webhooks are used by Facesign to notify integrated systems about relevant events (for example, the signing of a document). To ensure that these notifications:

* Are originating from Facesign,
* Have not been altered in transit,
* Are not reused improperly,

a **JWT token** is added to each webhook sent.

***

### JWT concept

The **JWT (JSON Web Token)** is a digitally signed token standard that contains relevant information about the sent event. It is composed of three parts:

* **Header**: metadata about the type of token and algorithm used.
* **Payload**: event data, such as timestamps, event type, identifiers.
* **Signature**: digital signature that guarantees the integrity of the content.

This token works like a sealed envelope: any attempt to change its content invalidates the signature.

***

### Process operation

#### Webhook issuance by Facesign

1. Facesign generates a JWT containing the event data.
2. The JWT is signed with a secure key.
3. The webhook is sent via an HTTP request, with the JWT included in the request header.

#### Processing and validation in the receiving system

1. The receiving system extracts the JWT from the received request.
2. The token is validated for origin, signature, and temporal validity.
3. The event data is processed according to the application's needs.

***

### Example of sent webhook

```http
POST /your-endpoint HTTP/1.1
Host: yourcompany.com
Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

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

### Example of JWT validation (in Python)

```python
import jwt

# Secret key provided by Facesign
FACESIGN_SECRET = "your_facesign_secret_key"

# Received token
token = "<JWT_RECEIVED_IN_HEADER>"

try:
    payload = jwt.decode(token, FACESIGN_SECRET, algorithms=["HS256"], audience="yourcompany.com")
    print("Valid webhook:", payload)
except jwt.ExpiredSignatureError:
    print("Error: Token expired.")
except jwt.InvalidTokenError:
    print("Error: Invalid token.")

```

### Elements that should be validated in the token

* `iss`: Confirms that the token was issued by Facesign.
* `aud`: Ensures that the token is intended for the correct application.
* `iat` and `exp`: Verify the token's temporal validity.
* `jti`: Unique identifier of the token, useful to prevent reprocessing of messages.

### Security recommendations

* **Use of HTTPS**: The webhook receiving endpoint must operate under HTTPS, ensuring protection of data in transit.
* **Token expiration**: Issued tokens have a short validity period. It is essential that expiration verification is implemented.
* **Mitigation of replay attacks**: It is recommended to temporarily store the values of `jti` of tokens already processed, to avoid repeated execution of the same event.
* **Protection of the secret key**: The key used to verify the JWT signature must be stored securely, without public exposure or in versioned repositories.