Webhook HMAC Signature

To ensure the authenticity and integrity of webhook events sent from StoneX Payments, webhook payloads can be signed using an HMAC‑SHA256 signature. This allows you to verify that incoming webhook notifications are genuinely sent by StoneX Payments and have not been tampered with in transit.

Clients are provisioned with their unique 256-bit secret key, generated using a cryptographically secure random process. When a webhook is sent, StoneX computes an HMAC signature of the payload using the client-specific secret key. Clients are expected to independently compute the same signature on receipt of the webhook and compare it with the signature included in the request. If the signatures match, the payload can be considered valid and trusted.

📘
Important!
HMAC key will be provisioned by the StoneX Payments API integration team for each API client on an ad-hoc basis and is not enabled for all clients by default.
When enabled, outbound webhook requests receive an X-Webhook-Signature: sha256 = < lowercase-hex > header computed as HMAC-SHA256 over the exact request body bytes, keyed by the UTF-8 bytes of the secret.

Best Practices for Clients

Treat your HMAC secret key as sensitive credentials and store it securely.
Never share the secret via email, chat, or ticketing systems.
Use secure channels (e.g. one-time secret sharing links) when receiving or rotating secrets.
Reject any webhook where the computed signature does not match the provided signature.

This feature ensures that all webhook communications are secure, verifiable, and tamper-resistant, providing a robust foundation for event-driven integrations with the StoneX Payments API.