Secure Webhook Signature Validation

To protect your receiving server from Man-in-the-Middle (MitM) attacks or spoofing, AISoule signs all outbound webhook POST requests. You can cryptographic check this signature to verify that the query was dispatched exclusively by AISoule.

The Validation Header

Every webhook request includes a security signature header:

X-AISoule-Signature: sha256=17df2033bc653842c019d6575791a82f3c0b5f1025de03194a0d9b4b0a48a9b2

This header contains the prefix sha256= followed by a hex-encoded HMAC-SHA256 digest of the raw JSON request body payload, generated using your webhook configuration's Secret Key as the cryptographic salt.

Step-by-Step Validation Guide

To validate incoming payloads:

1. Extract the raw body: Retrieve the raw request body bytes before your framework parses it into JSON.
2. Compute local HMAC: Generate an HMAC-SHA256 hash of the raw body bytes, using your webhook's unique Secret Key (from Settings dashboard).
3. Compare hashes securely: Use a constant-time string comparison function to prevent timing attacks. Verify if your computed hash matches the X-AISoule-Signature header value.

!WARNING Do NOT parse the request body to JSON first, as formatting changes (spaces, line breaks) will cause signature validation failure. Always compute the hash using the raw, original payload bytes.