Signature Verification

Use this page to verify webhook authenticity before you accept or process a payload.

Current Signature Headers

Doqlo sends these headers on webhook requests:

• X-Doqlo-Event
• X-Doqlo-Event-Id
• X-Doqlo-Timestamp
• X-Doqlo-Signature
• User-Agent: Doqlo-Webhook/1.0

Current signature format:

• X-Doqlo-Signature: v1=<hex>
• X-Doqlo-Timestamp: <unix-seconds>
• signing input: <timestamp>.<raw_body>
• algorithm: HMAC-SHA256

Current delivery envelope limits are:

• 2,048 UTF-8 bytes for the configured receiver URL;
• 64 KiB for the generated request body;
• 8 KiB for total request headers;
• 2 KiB for each request-header value;
• 16 KiB for response headers accepted by the delivery client; and
• 512 UTF-8 bytes for the retained response excerpt.

Verification Steps

1. Read the raw request body exactly as received.
2. Read X-Doqlo-Timestamp.
3. Compute HMAC-SHA256 over <timestamp>.<raw_body> with your webhook_secret.
4. Prefix the hex digest with v1=.
5. Compare the computed value with X-Doqlo-Signature.
6. Reject the request if the values do not match.

Example

timestamp='1710590400'
signature='v1=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
secret='your-webhook-secret'
body="$(cat payload.json)"

expected="v1=$(printf '%s' "$timestamp.$body" | openssl dgst -sha256 -hmac "$secret" -binary | xxd -p -c 256)"

test "$signature" = "$expected"

Important Notes

• Use the raw body, not a re-serialized JSON object.
• Verify the signature before you trust the payload contents.
• Store and compare event_id after signature verification so retries remain idempotent.