{"id":1116,"date":"2026-05-18T13:00:00","date_gmt":"2026-05-18T18:00:00","guid":{"rendered":"https:\/\/tolinku.com\/blog\/?p=1116"},"modified":"2026-03-07T03:34:44","modified_gmt":"2026-03-07T08:34:44","slug":"webhook-security-signing","status":"publish","type":"post","link":"https:\/\/tolinku.com\/blog\/webhook-security-signing\/","title":{"rendered":"Webhook Security: Signing and Verification"},"content":{"rendered":"\n

Webhooks are one of the most useful patterns in modern API design. They let your deep linking platform push events to your server in real time: clicks, installs, conversions, referral completions. But there is a problem. A webhook endpoint is just a URL that accepts POST requests. Without proper security, anyone who discovers that URL can send fabricated events to your server.<\/p>\n\n\n\n

Imagine an attacker sending fake conversion events to your webhook receiver. Your system credits referral rewards that were never earned, updates analytics with phantom data, or triggers automation workflows based on events that never happened. This is not a theoretical risk. Webhook spoofing is a well-documented attack vector<\/a>, and the consequences range from corrupted data to financial loss.<\/p>\n\n\n\n

This article covers how webhook security signing works, how to verify signatures in your code, and how to layer additional protections against replay attacks and unauthorized access. If you are building webhook integrations for deep linking<\/a>, this is essential reading.<\/p>\n\n\n\n

\"Tolinku\nThe webhooks page with create form, webhook list, and delivery log.<\/em><\/p>\n\n\n\n

Why Webhook Security Matters<\/h2>\n\n\n\n

When you register a webhook endpoint with a platform like Tolinku<\/a>, you are creating a trust relationship. The platform promises to send legitimate event data to your URL. Your server promises to process it and respond with a status code. But HTTP alone does not enforce that trust.<\/p>\n\n\n\n

Without signature verification, your webhook receiver has no way to answer a fundamental question: did this request actually come from the platform, or did someone else send it?<\/p>\n\n\n\n

The risks break down into three categories:<\/p>\n\n\n\n

Spoofed events.<\/strong> An attacker crafts a POST request that looks like a legitimate webhook payload and sends it to your endpoint. If your server blindly trusts the request body, it processes the fake event as real.<\/p>\n\n\n\n

Tampered payloads.<\/strong> A man-in-the-middle intercepts a legitimate webhook in transit and modifies the payload before it reaches your server. The event is real, but the data has been altered.<\/p>\n\n\n\n

Replay attacks.<\/strong> An attacker captures a legitimate, signed webhook request and resends it minutes, hours, or days later. The signature is valid because the payload has not changed, but the event is being processed a second time.<\/p>\n\n\n\n

HMAC signing addresses all three of these risks.<\/p>\n\n\n\n

How HMAC-SHA256 Signing Works<\/h2>\n\n\n\n

HMAC<\/a> (Hash-based Message Authentication Code) is a cryptographic mechanism for verifying both the integrity and authenticity of a message. When applied to webhooks, the process works like this:<\/p>\n\n\n\n

    \n
  1. When you create a webhook endpoint, the platform generates a shared secret. Only you and the platform know this secret.<\/li>\n
  2. When the platform sends a webhook, it computes an HMAC-SHA256 hash of the request body using the shared secret as the key.<\/li>\n
  3. The platform includes the resulting signature in a request header (typically X-Webhook-Signature<\/code> or similar).<\/li>\n
  4. Your server receives the request, computes its own HMAC-SHA256 hash of the request body using the same shared secret, and compares the result to the signature in the header.<\/li>\n
  5. If the signatures match, the request is authentic and unmodified. If they do not match, the request was either forged or tampered with.<\/li>\n<\/ol>\n\n\n\n

    The critical property of HMAC is that you cannot compute a valid signature without knowing the secret. An attacker who intercepts a webhook can see the payload and the signature, but they cannot forge a new signature for a different payload without the secret key.<\/p>\n\n\n\n

    Here is a simplified diagram of the flow:<\/p>\n\n\n\n

    Platform                              Your Server\n   |                                      |\n   |-- Compute HMAC(secret, body) ------->|\n   |-- Send POST with signature header -->|\n   |                                      |-- Compute HMAC(secret, body)\n   |                                      |-- Compare signatures\n   |                                      |-- Accept or reject\n<\/code><\/pre>\n\n\n\n
    The RFC 2104<\/a> specification defines HMAC. SHA-256 is the hash function used in most modern implementations because it provides a strong balance of security and performance.<\/p>\n\n\n\n
    Verifying Webhook Signatures in Node.js<\/h2>\n\n\n\n
    Here is a complete example of verifying webhook signatures in an Express application. This implementation covers the essentials: extracting the signature header, computing the expected signature, and using a timing-safe comparison.<\/p>\n\n\n\n
    const crypto = require('crypto');\nconst express = require('express');\n\nconst app = express();\n\n\/\/ Important: use raw body for signature verification.\n\/\/ JSON parsing alters whitespace and key order, which\n\/\/ changes the hash.\napp.use('\/webhooks', express.raw({ type: 'application\/json' }));\n\nconst WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;\n\nfunction verifySignature(payload, signatureHeader) {\n  if (!signatureHeader) {\n    return false;\n  }\n\n  const expectedSignature = crypto\n    .createHmac('sha256', WEBHOOK_SECRET)\n    .update(payload)\n    .digest('hex');\n\n  \/\/ Use timingSafeEqual to prevent timing attacks.\n  \/\/ Both buffers must be the same length.\n  const expected = Buffer.from(expectedSignature, 'hex');\n  const received = Buffer.from(signatureHeader, 'hex');\n\n  if (expected.length !== received.length) {\n    return false;\n  }\n\n  return crypto.timingSafeEqual(expected, received);\n}\n\napp.post('\/webhooks\/tolinku', (req, res) => {\n  const signature = req.headers['x-webhook-signature'];\n\n  if (!verifySignature(req.body, signature)) {\n    console.warn('Webhook signature verification failed');\n    return res.status(401).json({ error: 'Invalid signature' });\n  }\n\n  \/\/ Signature is valid. Parse and process the event.\n  const event = JSON.parse(req.body.toString());\n  console.log('Verified event:', event.event);\n\n  \/\/ Process the event asynchronously to respond quickly.\n  processEvent(event).catch(console.error);\n\n  res.status(200).json({ received: true });\n});\n<\/code><\/pre>\n\n\n\n
    A few critical details in this code:<\/p>\n\n\n\n
    Use the raw request body.<\/strong> The signature is computed over the exact bytes sent by the platform. If you parse the JSON first and then re-serialize it, whitespace differences or key reordering will produce a different hash. Always compute the HMAC over the raw body buffer.<\/p>\n\n\n\n
    Use crypto.timingSafeEqual<\/code>.<\/strong> A naive string comparison (===<\/code>) leaks timing information. An attacker can measure how long the comparison takes to determine how many bytes of the signature are correct, then brute-force the rest. The timingSafeEqual<\/code><\/a> function takes constant time regardless of where the mismatch occurs.<\/p>\n\n\n\n
    Return 401 for invalid signatures.<\/strong> Do not return 200 for failed verification. A 401 response tells the sender (and any monitoring systems) that the request was rejected for authentication reasons.<\/p>\n\n\n\n
    Preventing Replay Attacks with Timestamps<\/h2>\n\n\n\n
    HMAC signing alone does not prevent replay attacks. If an attacker captures a valid signed request, the signature remains valid indefinitely because the payload has not changed. To mitigate this, include a timestamp in the signed payload and enforce a tolerance window on the receiving end.<\/p>\n\n\n\n
    Most webhook platforms include a timestamp header alongside the signature. The signature is computed over both the timestamp and the body, so an attacker cannot modify the timestamp without invalidating the signature.<\/p>\n\n\n\n
    const TIMESTAMP_TOLERANCE_MS = 5 * 60 * 1000; \/\/ 5 minutes\n\nfunction verifySignatureWithTimestamp(payload, signatureHeader, timestampHeader) {\n  if (!signatureHeader || !timestampHeader) {\n    return false;\n  }\n\n  \/\/ Check timestamp freshness.\n  const timestamp = parseInt(timestampHeader, 10);\n  const now = Date.now();\n\n  if (Math.abs(now - timestamp) > TIMESTAMP_TOLERANCE_MS) {\n    console.warn('Webhook timestamp outside tolerance window');\n    return false;\n  }\n\n  \/\/ The signed content includes the timestamp to prevent\n  \/\/ an attacker from replacing the timestamp on a captured\n  \/\/ request.\n  const signedContent = `${timestampHeader}.${payload.toString()}`;\n\n  const expectedSignature = crypto\n    .createHmac('sha256', WEBHOOK_SECRET)\n    .update(signedContent)\n    .digest('hex');\n\n  const expected = Buffer.from(expectedSignature, 'hex');\n  const received = Buffer.from(signatureHeader, 'hex');\n\n  if (expected.length !== received.length) {\n    return false;\n  }\n\n  return crypto.timingSafeEqual(expected, received);\n}\n<\/code><\/pre>\n\n\n\n
    A five-minute tolerance window is a reasonable default. It accounts for clock drift between servers and network latency while still blocking replays of old requests. The Standard Webhooks<\/a> specification recommends a similar approach, combining a timestamp with the signature to form a verifiable, time-bound token.<\/p>\n\n\n\n
    For additional replay protection, you can store processed event IDs and reject duplicates. This provides defense in depth: even if a replayed request somehow falls within the timestamp window, the duplicate ID check catches it.<\/p>\n\n\n\n
    IP Allowlisting<\/h2>\n\n\n\n
    Signature verification is your primary defense, but IP allowlisting adds a useful secondary layer. If your webhook platform publishes a list of IP addresses that send webhook traffic, you can configure your firewall or application to reject requests from any other source.<\/p>\n\n\n\n
    const ALLOWED_IPS = new Set([\n  \/\/ Replace with your platform's published webhook IPs.\n  '203.0.113.10',\n  '203.0.113.11',\n  '198.51.100.5',\n]);\n\nfunction isAllowedIP(req) {\n  const clientIP = req.headers['x-forwarded-for']?.split(',')[0].trim()\n    || req.socket.remoteAddress;\n  return ALLOWED_IPS.has(clientIP);\n}\n\napp.post('\/webhooks\/tolinku', (req, res) => {\n  if (!isAllowedIP(req)) {\n    return res.status(403).json({ error: 'Forbidden' });\n  }\n\n  \/\/ Continue with signature verification...\n});\n<\/code><\/pre>\n\n\n\n
    IP allowlisting is not a substitute for signature verification. IP addresses can be spoofed at the network layer, and platforms may add new IPs without notice. Treat it as defense in depth, not a standalone mechanism.<\/p>\n\n\n\n
    TLS and HTTPS Requirements<\/h2>\n\n\n\n
    Every webhook endpoint should be served over HTTPS. This is non-negotiable. Without TLS, the entire webhook payload (including the signature header) travels in plaintext across the network. A network-level attacker could read, modify, or replay any request.<\/p>\n\n\n\n
    Most webhook platforms, including Tolinku<\/a>, require HTTPS endpoints and will refuse to deliver events to plain HTTP URLs. If you are developing locally, tools like ngrok<\/a> or localtunnel<\/a> provide HTTPS tunnels for testing.<\/p>\n\n\n\n
    Beyond basic TLS, consider these additional transport-layer practices:<\/p>\n\n\n\n