Skip to main content

Verifying webhook signatures

Check that webhook alerts come from PriceShape and weren't changed on the way.

Written by Sarah Fogtmand

Every webhook request is signed. If alerts go to your own server, you can check the signature to confirm a request came from PriceShape and wasn't changed on the way.

Sending alerts to Slack or Teams? They don't check signatures, so there's nothing to set up.


Find your signing secret

  1. Open the workflow in the workflow builder and click the Webhook action.

  2. The secret is under Signing secret, hidden by default. Click the eye icon to show it, or the copy icon to copy it.

The secret appears once you save the workflow. Until then, the field says "The signing secret appears here when you save the workflow."


One secret per endpoint

All webhook actions on your account that send to the same endpoint share one signing secret, also across workflows. So if five workflows post to your server, you only need one secret there. Below the secret, you can see when it was created and how many webhooks use it, for example Used by 3 webhooks to this endpoint.

Two URLs count as the same endpoint when they only differ in:

  • Upper or lower case in https:// or the domain

  • A default port, such as :443

  • A trailing /

  • The query string (?…) or fragment (#…)

For example, https://hooks.example.com/alerts and https://Hooks.Example.com/alerts/?team=pricing share a secret. The path is case-sensitive, so /alerts and /Alerts get different secrets.

Alerts are still sent to the full URL you entered, query string included. A duplicated workflow keeps the same secret, and secrets are never shared between PriceShape accounts.


What each request contains

Every request has an X-PriceShape-Signature header:

X-PriceShape-Signature: t=1763380800,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
  • t is the time the request was signed, in Unix seconds.

  • v1 is the signature: a hex-encoded HMAC-SHA256.


Check a request

  1. Read the raw request body exactly as it arrived, before parsing the JSON. If you parse it and turn it back into text, the bytes can change and the signature won't match.

  2. Take t and v1 from the header.

  3. Check that t is less than five minutes from your server's current time, earlier or later. If it isn't, reject the request. This stops anyone from resending an old request later.

  4. Join t, a dot, and the raw body: <t>.<raw body>.

  5. Calculate the HMAC-SHA256 of that text with your signing secret as the key, and hex-encode it.

  6. Compare it with v1 using a constant-time comparison. If they don't match, reject the request, for example with 401.

Keep the secret out of your code. Both examples read it from the PRICESHAPE_WEBHOOK_SECRET environment variable.

Example: Python (Flask)

import hashlib
import hmac
import os
import time
from typing import Optional
 
from flask import Flask, abort, request
 
SECRET = os.environ["PRICESHAPE_WEBHOOK_SECRET"].encode()
TOLERANCE_SECONDS = 300
 
 
def verify(raw_body: bytes, header: Optional[str]) -> bool:
    if not header:
        return False
    parts = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    try:
        t = int(parts["t"])
        v1 = parts["v1"]
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) >= TOLERANCE_SECONDS:
        return False
 
    expected = hmac.new(SECRET, f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)
 
 
app = Flask(__name__)
 
 
@app.post("/priceshape-alerts")
def priceshape_alerts():
    # get_data() returns the exact bytes received
    if not verify(request.get_data(), request.headers.get("X-PriceShape-Signature")):
        abort(401)
 
    alert = request.get_json()
    # Handle the alert here
    return "", 200

Example: Node.js (Express)

const crypto = require("node:crypto")
const express = require("express")
 
const SECRET = process.env.PRICESHAPE_WEBHOOK_SECRET
const TOLERANCE_SECONDS = 300
 
function verify(rawBody, header) {
  if (!header) return false
  const parts = Object.fromEntries(
    header.split(",").map((part) => {
      const i = part.indexOf("=")
      return [part.slice(0, i), part.slice(i + 1)]
    }),
  )
  const t = Number(parts.t)
  if (!Number.isInteger(t) || !parts.v1) return false
  if (Math.abs(Math.floor(Date.now() / 1000) - t) >= TOLERANCE_SECONDS) return false
 
  const expected = crypto.createHmac("sha256", SECRET).update(`${t}.`).update(rawBody).digest()
  const received = Buffer.from(parts.v1, "hex")
  return received.length === expected.length && crypto.timingSafeEqual(received, expected)
}
 
const app = express()
 
// express.raw keeps the body as the exact bytes received
app.post("/priceshape-alerts", express.raw({ type: "application/json" }), (req, res) => {
  if (!verify(req.body, req.get("X-PriceShape-Signature"))) return res.sendStatus(401)
 
  const alert = JSON.parse(req.body.toString("utf8"))
  // Handle the alert here
  res.sendStatus(200)
})
 
app.listen(3000)

If the signature doesn't match

  • It never matches: Check that you're using the raw body and not parsed JSON, and that the secret on your server has no extra spaces. Compare the last 4 characters with the ones shown in PriceShape.

  • It fails now and then: Your server's clock may be off. Requests more than five minutes from your server's time are rejected, so keep the clock in sync.

  • It matched before, then stopped: Someone may have generated a new secret for the endpoint. Copy the current one from any webhook action that sends to it. Alerts your server rejected in the meantime are not sent again.


Generating a new secret

If your secret has been exposed, generate a new one:

  1. Open the webhook action and click Generate new secret.

  2. The confirmation shows the endpoint and every workflow that uses it. Click Generate new secret to continue.

  3. Save the workflow. The new secret now applies to every webhook on that endpoint, including alerts that were already waiting to be sent.

  4. Update the secret on your server straight away. Until you do, it will reject alerts from all of those workflows, and those alerts are not sent again.

Changed your mind before saving? Click Keep current secret to discard the new one.

If someone changed the same endpoint's secret in another workflow while you were editing, your save is refused with "This endpoint's secret was changed in another workflow. Generate a new one and save again." The builder refreshes, so click Generate new secret again and save.

Did this answer your question?