📡 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 (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):

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:

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