Skip to main content
Every webhook delivery includes an X-Signature header so you can confirm it came from Etherfuse and wasn’t tampered with.

How It Works

When you create a webhook, the response includes a secret — a base64-encoded HMAC key. Store it securely; it is only returned once. Each delivery signs the payload with that secret:
  1. The JSON body is canonicalized (RFC 8785 JCS — deterministic key ordering, no extra whitespace)
  2. HMAC-SHA256 is computed over the canonicalized string using your secret (decoded from base64)
  3. The result is sent as X-Signature: sha256={hex}

Verifying the Signature

  1. Canonicalize the received JSON body
  2. Decode your webhook secret from base64
  3. Compute HMAC-SHA256 over the canonicalized string
  4. Compare sha256={hex_result} to the X-Signature header using a constant-time comparison
The signature is computed over the canonicalized JSON, not the raw request body. You must canonicalize before comparing or the signature will not match.

Rust

Node.js

Python

Delivery & Retries

Failed deliveries (non-2xx responses or connection errors) are retried up to 3 times with 5-second delays between attempts. Return a 2xx promptly to avoid unnecessary retries.