Webhook Security

When you configure a webhook_secret on your assistant, HMS Sovereign signs all webhook requests. You should verify these signatures to ensure requests come from HMS Sovereign.

Signature Format

HMS Sovereign uses HMAC-SHA256 to sign webhooks. The signature is included in the X-Webhook-Signature header.

How It's Calculated

message = timestamp + "." + raw_request_body
signature = "sha256=" + HMAC-SHA256(secret, message)

The X-Webhook-Signature header value is prefixed with sha256=. Strip this prefix before comparing with your computed HMAC.

Verification Examples

Python

Node.js

Go

PHP

Best Practices

Always verify in production - Never skip signature verification in production

Use timing-safe comparison - Prevent timing attacks with constant-time comparison

Check timestamp freshness - Optionally reject requests older than 5 minutes to prevent replay attacks

Store secret securely - Use environment variables, not hardcoded values

Log verification failures - Monitor for suspicious activity

Timestamp Validation

Optionally validate the timestamp to prevent replay attacks:

See WebhookHeaders Schema for header details.

Signature Format#

How It's Calculated#

Verification Examples#

Python#

Node.js#

Go#

PHP#

Best Practices#

Timestamp Validation#