To ensure the security of callback requests, it is strongly recommended to enable Webhook HMAC signature verification in production environments to prevent forged or tampered requests.
Algorithm Overview#
Emix uses the HMAC-SHA256 algorithm to sign webhook callbacks, so you can confirm that a callback really comes from Emix and that its body was not changed in transit.Signature Generation Process:1.
Take the raw request body: the exact bytes of the JSON body Emix sends (UTF-8), before any parsing.
2.
Calculate HMAC-SHA256 signature with your Webhook HMAC Key as the secret:signature = HMAC-SHA256(rawRequestBody, webhookHmacKey)
3.
Base64 encode the signature:finalSignature = Base64.encode(signature)
Compute the signature over the raw body exactly as received. Do not parse the JSON and serialize it again before signing: changes in whitespace or key order will make the signature fail.
Obtain Webhook HMAC Key#
You can generate and view your webhookHmacKey on the Emix Settings Page (Settings β Webhook HMAC Key). Generating a new key replaces the old one; callbacks sent afterwards are signed with the new key.The webhookHmacKey is used to verify that callback requests originate from Emix's official servers. Keep this key secure and never expose it or commit it to code repositories.
Once you have generated a webhookHmacKey on the settings page, every callback request includes the following HTTP headers. If no key has been generated, callbacks are sent without signature headers.X-Emix-Signature#
Required: Yes (when a Webhook HMAC Key exists)
Description: Base64-encoded HMAC-SHA256 signature of the raw request body, using your webhookHmacKey as the secret. New integrations should verify this header.
X-Kie-Signature#
Required: Yes (when a Webhook HMAC Key exists)
Description: Legacy header with exactly the same value as X-Emix-Signature. It is kept for backward compatibility, so existing integrations that verify it keep working.
Signature generation rule:#
base64(HMAC-SHA256(rawRequestBody, webhookHmacKey))
rawRequestBody is the raw callback body (UTF-8 bytes) as received by your server
webhookHmacKey is the key you generated in the console
Webhook Verification Process#
Follow these steps to verify the legitimacy of webhook requests:1
Read the Raw Body and Header
Read the raw request body bytes before any JSON parsing, and extract the
X-Emix-Signature header.
2
Generate Signature
Using your locally stored
webhookHmacKey, compute the HMAC-SHA256 of the raw body and Base64 encode it.
3
Compare Signatures
Compare the computed signature with
X-Emix-Signature using a constant-time comparison algorithm to prevent timing attacks.
Complete Example Code#
Here are complete examples of implementing webhook signature verification in popular programming languages:Example Webhook Request#
Here's what a signed webhook request looks like:Notes#
Respond with a 2xx status within 10 seconds. Emix waits at most 10 seconds for your endpoint and does not retry a failed callback, so use the task detail API to recover results you missed.
If you already verify X-Kie-Signature, it keeps working with the same value. Switching to X-Emix-Signature needs no other change.
If your key leaks, generate a new one on the settings page and update your server.