Signature and security

Your webhook endpoint is public: anyone who knows the URL can send you forged requests. Exoid signs every request with HMAC-SHA256 and you have to verify the signature before trusting the content.

How Exoid signs requests

Exoid signs the unparsed request body (the raw body, byte for byte) with HMAC-SHA256, using the campaign’s Webhook Secret.
The signature travels in the X-Signature header, in the format sha256=<hex>.
Your endpoint has to recreate the signature and compare it with the one received. If they don’t match, reject the request.

Verification procedure

Read the raw body

Receive the body as an unparsed Buffer, without applying any JSON middleware.

Extract the header

Take the value of X-Signature from the incoming request.

Recompute the HMAC

Compute HMAC-SHA256 of the raw body with the campaign’s Webhook Secret and format the result as sha256=<hex>.

Compare

If the computed signature doesn’t match the one received, answer 401 and stop processing.

Process the payload

Only at this point run JSON.parse on the body and use the data.

Node.js example (Express)

verify-signature.js

const crypto = require("crypto");
const express = require("express");
const app = express();

// Use express.raw to access the unparsed body and verify the signature
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-signature"];
  const expected =
    "sha256=" +
    crypto
      .createHmac("sha256", process.env.WEBHOOK_SECRET)
      .update(req.body) // raw Buffer
      .digest("hex");

  if (sig !== expected) return res.status(401).send("Invalid signature");

  const payload = JSON.parse(req.body);
  console.log("Webhook received:", payload);

  res.sendStatus(200);
});

app.listen(3000, () => console.log("Webhook listener running on :3000"));

You have to compute the HMAC on the unparsed body. If you run JSON.parse (or middleware like express.json()) before verifying and then re-serialize the object, the bytes change — spacing, key order, escaping — and the comparison fails even on perfectly legitimate requests. Always use the raw Buffer, for example with express.raw.

Compare signatures in constant time (for example with crypto.timingSafeEqual) so you don’t leak information through response timing. And never write the Webhook Secret to your application logs.

An endpoint that answers 401 gets no retries: 401 is a permanent error. Make sure verification is correct before going to production, otherwise you lose events.

Advanced settings

Webhooks

Signature and security

How Exoid signs requests

Verification procedure

Node.js example (Express)

Next steps

Payload reference

Configuration

​How Exoid signs requests

​Verification procedure

​Node.js example (Express)

​Next steps

Payload reference

Configuration

How Exoid signs requests

Verification procedure

Node.js example (Express)

Next steps