# 📡 Webhook Documentation

NVSEP uses webhooks to notify your systems about important events, such as the creation of an exclusion. This guide outlines how to securely handle, verify, and respond to these webhooks.

## 🔐 Security

All outbound webhook requests from NVSEP are **signed** using a secure HMAC SHA-256 signature. This ensures the integrity and authenticity of the message.

* Each request will contain an `x-nvsep-hmac-sha256` header.
* The signature is computed using your **webhook signing key**, which is available from your [NVSEP Dashboard](https://portal.nvsep.org/admin) (insert actual link or image below).


> 🛡️ **Keep your signing key safe!**
Do not expose it publicly or include it in client-side code.


**Example header:**


```
x-nvsep-hmac-sha256: 68f4c7c65e0fbd06c6b9dcd14e9e6e8f18e2c3f46b83f7cdb2ebfd3e8b99c882
```

**Signature verification (example in pseudocode):**


```python
import hmac
import hashlib

def verify_signature(payload, signature, signing_key):
    computed = hmac.new(signing_key.encode(), payload.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(computed, signature)
```

## 🔁 Retry Policy

If your endpoint fails to respond with a `2XX` status code, NVSEP will **retry delivery up to 6 times** with exponential backoff:

| Attempt | Delay (minutes) |
|  --- | --- |
| 1 | 60 |
| 2 | 60 |
| 3 | 300 (5 hours) |
| 4 | 900 (15 hours) |
| 5 | 3600 (60 hours) |
| 6 | 7200 (120 hours) |
| 7+ | 86400 (1 day) |


> ✅ A **2XX response** is required to stop retries.


## 📬 Webhook Events

The following webhook events are currently supported:

### `exclusions.created`

Triggered when a new exclusion is successfully registered in the NVSEP platform.

**Headers:**


```
Content-Type: application/json
x-nvsep-hmac-sha256: <signature>
```

## ✅ Best Practices

* **Always verify** the HMAC signature before processing the payload.
* Use **HTTPS** for your webhook endpoints.
* Implement **idempotency** in your handler to avoid processing duplicates.
* Log events and retry attempts for auditing and debugging.