Dumpster Controls · agent page

This is the agent-optimized version of https://dumpstercontrols.io/help/api/verify-webhook-signatures: the same content as the human page, without scripts, styles, animations or navigation. People should open the full page.

Canonical page
https://dumpstercontrols.io/help/api/verify-webhook-signatures
Last updated
2026-08-22
Tokens
829 tokens (cl100k_base), within the 2,500-token budget for a help page
Size
7.3 KB for this page, against 23 KB for the human page (68% smaller)
Markdown
https://dumpstercontrols.io/help/api/verify-webhook-signatures.md, or send Accept: text/markdown to the canonical URL
Cite as
Verify webhook signatures (HMAC). Dumpster Controls. https://dumpstercontrols.io/help/api/verify-webhook-signatures (accessed 2026-11-16).
More for agents
Facts sheet · llms.txt · llms-full.txt · All agent pages · Product manual

Developer API · updated 2026-08-22

Verify webhook signatures (HMAC)

Every webhook delivery is signed so your server can prove it came from Dumpster Controls and was not tampered with. Verification is a dozen lines of code in any language. Never process an unverified webhook.

  1. ## The signature header
    Each delivery carries:
    ```
    X-DC-Signature: t=1755900000,v1=a1b2c3...
    ```
    t is the unix timestamp when we signed, and v1 is the hex HMAC-SHA256 of the string "<t>.<raw body>" computed with your endpoint secret (dcwh_...).
  2. ## Verification steps
  3. Read the RAW request body (before any JSON parsing; whitespace matters). 2. Parse t and v1 from the header. 3. Compute HMAC-SHA256(secret, t + "." + rawBody) and hex-encode it. 4. Compare with v1 using a constant-time comparison. 5. Reject if |now - t| is more than about 5 minutes (replay protection).
  4. ## Node.js example
    ```
    const crypto = require("crypto");
    ```
    function verify(rawBody, header, secret) {
    const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
    const expected = crypto.createHmac("sha256", secret)
    .update(parts.t + "." + rawBody).digest("hex");
    const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
    const sig = Buffer.from(parts.v1 || "");
    // timingSafeEqual THROWS on unequal lengths: guard first
    return fresh && sig.length === 64 &&
    crypto.timingSafeEqual(Buffer.from(expected), sig);
    }
    ```
  5. ## Python example
    ```
    import hmac, hashlib, time
    ```
    def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=") for p in header.split(","))
    expected = hmac.new(secret.encode(),
    f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(parts["t"])) < 300
    return fresh and hmac.compare_digest(expected, parts["v1"])
    ```
  6. ## Common mistakes
    Parsing the JSON and re-serializing it before hashing (key order changes, verification fails): always hash the raw bytes. Using == instead of a constant-time compare. Skipping the timestamp check, which allows replays of old captured deliveries.

Related guides

© 2026 Dumpster Controls. All rights reserved. Made in the USA.