Verify signatures

Every outbound delivery is signed with the destination’s secret, a whsec_-prefixed value that Hookie generates when you create the destination. Each delivery is signed twice: with Hookie’s own Hookie-Signature header, and with the Standard Webhooks headers, so any Standard Webhooks library can verify it. Verify either one before trusting the payload. You never have to write it down. The secret is encrypted at rest and masked in the console. It is shown in full when you create the destination, and owners and admins can reveal it again at any time: Reveal secret, the eye button on the destination’s Signing secret row, fetches it on demand for them only, and every reveal is written to your audit log. Rotate issues a new secret and shows it to you. The secret it replaces keeps signing for 24 hours: every delivery in that window carries two signatures, one per secret, so your receiver keeps verifying while you update it (see Rotating the secret).

This page is about the deliveries Hookie sends. To have an endpoint check the signature a provider such as Stripe, GitHub or Shopify puts on the requests it receives, see Verify provider signatures.

The headers

Each delivery carries:

Hookie-Signature: t=1718000000,v1=5f2b8c…e11a
webhook-id: 4c7b…
webhook-timestamp: 1718000000
webhook-signature: v1,g0hM9SsE…1OE=
Hookie-Event-Id: 9d3f2a10-…
Hookie-Delivery-Id: 4c7b…
Hookie-Hop: 1

Hookie-Signature: t=<unix>,v1=<hex>, an HMAC-SHA256 (Stripe-style). For 24 hours after a rotation it carries a second v1: t=<unix>,v1=<new>,v1=<previous>.
webhook-id, webhook-timestamp, webhook-signature: the Standard Webhooks set. webhook-id is the delivery ID, the same on every retry of that delivery (a replay is a new delivery, with a new ID); webhook-timestamp is the same unix time as t; webhook-signature is v1,<base64>, and for 24 hours after a rotation v1,<new> v1,<previous>, space-separated.
Hookie-Event-Id: the event ID. Dedupe on this, since delivery is at-least-once and unordered.
Hookie-Delivery-Id: the delivery, useful in logs. It stays the same across the retries of one delivery (every attempt is listed under it in the console’s delivery drawer), and a replay is a new delivery with a new ID.
Hookie-Hop: how many times this event has passed through Hookie. If your service forwards the event into Hookie again, pass this header on: Hookie refuses an event at 8 hops, which stops a delivery loop.

Deliveries never follow redirects. A 3xx answer is recorded as a failed attempt naming the Location it pointed to, and is not retried: a redirect means the destination URL is wrong, so update it rather than letting a signed event be forwarded somewhere you did not choose.

Two schemes, one secret

You only need to verify one of them. Hookie-Signature is unchanged, so an existing receiver keeps working; the Standard Webhooks headers let you use an off-the-shelf library instead.

	`Hookie-Signature`	Standard Webhooks
Headers	`Hookie-Signature: t=<unix>,v1=<sig>`	`webhook-id`, `webhook-timestamp`, `webhook-signature: v1,<sig>`
Signed string	`<t>.<raw body>`	`<webhook-id>.<webhook-timestamp>.<raw body>`
HMAC-SHA256 key	the UTF-8 bytes of the whole secret string, `whsec_` included	the base64-decoded bytes of what follows `whsec_` (36 bytes)
Signature encoding	lowercase hex	base64
During a rotation	`t=<unix>,v1=<new>,v1=<previous>`	`v1,<new> v1,<previous>` (space-separated)

If the destination has a body template (see Destination options), both signatures cover the templated body as sent, not the envelope. Verification is the same. Both are computed from the same signing secret, but each derives its HMAC key the way its own scheme says, so the keys differ. Hookie’s secrets are whsec_ followed by 48 hexadecimal characters. Hex digits are all base64 characters and 48 is a multiple of 4, so the part after whsec_ is already valid base64: it decodes to 36 bytes, and every Standard Webhooks library accepts the secret exactly as Hookie shows it. Do not hex-decode it, and do not use the text of it as the Standard Webhooks key: base64-decode the characters after whsec_. For either scheme: verify the exact raw body bytes, compare in constant time with each signature and accept the request if any of them matches, and reject a timestamp more than five minutes from now.

Verify Hookie-Signature

The signed string is <t>.<raw body>: the timestamp, a dot, then the exact request body bytes. Compute HMAC-SHA256(secret, "<t>.<body>") as lowercase hex, keyed with the whole secret string, and compare it with each v1 in the header.

const crypto = require("crypto");

// Hookie-Signature: "t=<unix>,v1=<hex>[,v1=<hex>]".
// Key: the secret string itself, whsec_ prefix included. Signed: "<t>.<raw body>".
function verifyHookie(secret, header, rawBody, toleranceSeconds = 300) {
  // v1 repeats during a secret rotation, so collect every one. (Object.fromEntries
  // would keep only the last, which is the PREVIOUS secret's signature.)
  const pairs = String(header ?? "").split(",").map((kv) => kv.split("="));
  const t = pairs.find(([k]) => k === "t")?.[1];
  const signatures = pairs.filter(([k]) => k === "v1").map(([, v]) => v);
  if (!t || signatures.length === 0) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false; // replay protection
  const expected = Buffer.from(crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"));
  return signatures.some((sig) => {
    const given = Buffer.from(sig);
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

import hashlib, hmac, time

# Hookie-Signature: "t=<unix>,v1=<hex>[,v1=<hex>]".
# Key: the secret string itself, whsec_ prefix included. Signed: "<t>.<raw body>".
def verify_hookie(secret: str, header: str, raw_body: bytes, tolerance: int = 300) -> bool:
    pairs = [p.split("=", 1) for p in (header or "").split(",") if "=" in p]
    t = next((v for k, v in pairs if k == "t"), None)
    signatures = [v for k, v in pairs if k == "v1"]  # two during a secret rotation
    if not t or not t.isdigit() or not signatures or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected.encode(), sig.encode()) for sig in signatures)

package webhooks

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"strconv"
	"strings"
	"time"
)

// VerifyHookie checks Hookie-Signature: "t=<unix>,v1=<hex>[,v1=<hex>]".
// Key: the secret string itself, whsec_ prefix included. Signed: "<t>.<raw body>".
func VerifyHookie(secret, header string, rawBody []byte) bool {
	var t string
	var sigs []string
	for _, part := range strings.Split(header, ",") {
		k, v, _ := strings.Cut(part, "=")
		switch k {
		case "t":
			t = v
		case "v1":
			sigs = append(sigs, v) // two during a secret rotation
		}
	}
	unix, err := strconv.ParseInt(t, 10, 64)
	if err != nil || len(sigs) == 0 || time.Since(time.Unix(unix, 0)).Abs() > 5*time.Minute {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(t + "."))
	mac.Write(rawBody)
	expected := []byte(hex.EncodeToString(mac.Sum(nil)))
	for _, sig := range sigs {
		if hmac.Equal(expected, []byte(sig)) {
			return true
		}
	}
	return false
}

require "openssl"

# Hookie-Signature: "t=<unix>,v1=<hex>[,v1=<hex>]".
# Key: the secret string itself, whsec_ prefix included. Signed: "<t>.<raw body>".
def verify_hookie(secret, header, raw_body, tolerance = 300)
  pairs = header.to_s.split(",").map { |p| p.split("=", 2) }
  t = pairs.find { |k, _| k == "t" }&.last
  signatures = pairs.select { |k, _| k == "v1" }.map(&:last) # two during a secret rotation
  return false if t.nil? || signatures.empty? || (Time.now.to_i - t.to_i).abs > tolerance
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{t}.#{raw_body}")
  signatures.any? { |sig| OpenSSL.secure_compare(expected, sig.to_s) }
end

Verify Standard Webhooks

The signed string is <webhook-id>.<webhook-timestamp>.<raw body>. Compute its HMAC-SHA256 as base64, keyed with the base64-decoded bytes after whsec_, and compare it with the signature after v1, in each space-separated entry of webhook-signature. Any Standard Webhooks library verifies these headers with the secret as-is: standardwebhooks on npm, PyPI and RubyGems, and github.com/standard-webhooks/standard-webhooks/libraries/go for Go. For example, in Node: new Webhook(secret).verify(rawBody, headers) (from standardwebhooks), which throws when no signature matches. Or, without a library:

const crypto = require("crypto");

// Standard Webhooks: webhook-id, webhook-timestamp, webhook-signature ("v1,<base64>[ v1,<base64>]").
// Key: the base64-DECODED bytes after "whsec_". Signed: "<id>.<timestamp>.<raw body>".
// headers: an object with lower-case names (Express's req.headers is one).
function verifyStandardWebhook(secret, headers, rawBody, toleranceSeconds = 300) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false;
  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const expected = Buffer.from(crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest("base64"));
  // Space-separated: two signatures during a secret rotation.
  return signatures.split(" ").some((versioned) => {
    const [version, sig] = versioned.split(",");
    const given = Buffer.from(sig ?? "");
    return version === "v1" && given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

import base64, hashlib, hmac, time

# Standard Webhooks: webhook-id, webhook-timestamp, webhook-signature ("v1,<base64>[ v1,<base64>]").
# Key: the base64-DECODED bytes after "whsec_". Signed: "<id>.<timestamp>.<raw body>".
# headers: a case-insensitive mapping (Flask's request.headers, Django's request.headers).
def verify_standard_webhook(secret: str, headers, raw_body: bytes, tolerance: int = 300) -> bool:
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not msg_id or not timestamp or not timestamp.isdigit() or not signatures:
        return False
    if abs(time.time() - int(timestamp)) > tolerance:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest())
    for versioned in signatures.split(" "):  # two during a secret rotation
        version, _, sig = versioned.partition(",")
        if version == "v1" and hmac.compare_digest(expected, sig.encode()):
            return True
    return False

package webhooks

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"net/http"
	"strconv"
	"strings"
	"time"
)

// VerifyStandardWebhook checks webhook-id, webhook-timestamp and webhook-signature
// ("v1,<base64>[ v1,<base64>]").
// Key: the base64-DECODED bytes after "whsec_". Signed: "<id>.<timestamp>.<raw body>".
func VerifyStandardWebhook(secret string, h http.Header, rawBody []byte) bool {
	id, ts, sigs := h.Get("webhook-id"), h.Get("webhook-timestamp"), h.Get("webhook-signature")
	unix, err := strconv.ParseInt(ts, 10, 64)
	if id == "" || sigs == "" || err != nil || time.Since(time.Unix(unix, 0)).Abs() > 5*time.Minute {
		return false
	}
	key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
	if err != nil {
		return false
	}
	mac := hmac.New(sha256.New, key)
	mac.Write([]byte(id + "." + ts + "."))
	mac.Write(rawBody)
	expected := []byte(base64.StdEncoding.EncodeToString(mac.Sum(nil)))
	for _, versioned := range strings.Split(sigs, " ") { // two during a secret rotation
		version, sig, _ := strings.Cut(versioned, ",")
		if version == "v1" && hmac.Equal(expected, []byte(sig)) {
			return true
		}
	}
	return false
}

require "base64"
require "openssl"

# Standard Webhooks: webhook-id, webhook-timestamp, webhook-signature ("v1,<base64>[ v1,<base64>]").
# Key: the base64-DECODED bytes after "whsec_". Signed: "<id>.<timestamp>.<raw body>".
# headers: a hash with lower-case names (in Rails: request.headers["webhook-id"] etc.).
def verify_standard_webhook(secret, headers, raw_body, tolerance = 300)
  id, timestamp, signatures = headers.values_at("webhook-id", "webhook-timestamp", "webhook-signature")
  return false if id.nil? || timestamp.nil? || signatures.nil?
  return false if (Time.now.to_i - timestamp.to_i).abs > tolerance
  key = Base64.strict_decode64(secret.delete_prefix("whsec_"))
  expected = Base64.strict_encode64(OpenSSL::HMAC.digest("SHA256", key, "#{id}.#{timestamp}.#{raw_body}"))
  signatures.split(" ").any? do |versioned| # two during a secret rotation
    version, sig = versioned.split(",", 2)
    version == "v1" && OpenSSL.secure_compare(expected, sig.to_s)
  end
end

Rotating the secret

Rotating is safe to do while deliveries are flowing:

Press Rotate on the destination (owner or admin). The new secret is shown to you.
For the next 24 hours every delivery is signed with both secrets, new first: Hookie-Signature: t=1718000000,v1=<new>,v1=<previous> and webhook-signature: v1,<new> v1,<previous>. A receiver that accepts any matching signature (as the verifiers above and every Standard Webhooks library do) keeps working whichever secret it holds.
Update your receiver to the new secret at any point in that window. The destination shows when the previous secret stops signing.
Once every receiver is on the new secret you can press Expire now to stop sending the previous signature early; otherwise it stops on its own after 24 hours.

Rotating again inside the window replaces the older of the two, so at most two secrets ever sign a delivery. A receiver that briefly needs to accept both can also hold both secrets and check each.

Express handler

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

// Capture the RAW body — signature is over the exact bytes.
app.post("/hook", express.raw({ type: "*/*" }), (req, res) => {
  const raw = req.body.toString("utf8");
  const ok = verifyHookie(process.env.HOOKIE_SECRET, req.get("Hookie-Signature"), raw);
  // or: verifyStandardWebhook(process.env.HOOKIE_SECRET, req.headers, raw)
  if (!ok) return res.status(401).end();

  const eventId = req.get("Hookie-Event-Id"); // dedupe on this — delivery is at-least-once
  const event = JSON.parse(raw);
  // … handle event …
  res.status(200).end();
});

Check that Hookie sent it (Web Bot Auth)

Production deliveries to a webhook destination also carry three headers from the Web Bot Auth scheme, which is HTTP Message Signatures (RFC 9421) with an Ed25519 key. They prove the request came from Hookie’s bot. They do not prove the body is intact: use the payload signatures above for that.

Signature-Agent: "https://hookie.ai"
Signature-Input: sig1=("@authority" "signature-agent");created=1718000000;keyid="kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k";alg="ed25519";expires=1718000300;nonce="…";tag="web-bot-auth"
Signature: sig1=:…:

To check one:

Fetch Hookie’s key directory at https://hookie.ai/.well-known/http-message-signatures-directory. It is a JSON Web Key Set, served as application/http-message-signatures-directory+json.
Find the key whose RFC 7638 thumbprint is the keyid. The keyid is the RFC 8037 thumbprint of the Ed25519 public key. Reject the request if no key matches.
Rebuild the signature base, three lines joined by newlines: "@authority": <the host you received the request on>, then "signature-agent": "https://hookie.ai" (the header’s value, quotes included), then "@signature-params": followed by the value of Signature-Input after sig1=.
Verify the Ed25519 signature in Signature (the base64 between the colons) over that base with the key. Reject the request if expires has passed.

Hookie signs a delivery to a webhook destination only. Slack, S3 and SQS destinations are not signed this way, and deliveries from a preview or test environment are never signed, so a test deployment cannot pass as Hookie’s production sender. Each attempt of a delivery gets fresh headers, with its own created, expires and nonce. If a destination sends its own Signature, Signature-Input or Signature-Agent header, Hookie sends none of the three on that destination’s deliveries. The partner’s header goes out unchanged, and those deliveries are not signed this way.

Notes

Verify against the raw bytes. Re-serializing the JSON will change the signature.
Reject the request if the headers are missing or no signature matches. Reject a timestamp more than five minutes old to limit replay.
Always compare with a constant-time function: crypto.timingSafeEqual (Node), hmac.compare_digest (Python), hmac.Equal (Go), OpenSSL.secure_compare (Ruby).
A destination’s URL is fixed once created, and a signature is only meaningful against the URL it was sent to. To move a destination, create the replacement and delete the old one.

Get started

Concepts

CLI

Guides

API reference

Verify signatures

The headers

Two schemes, one secret

Verify Hookie-Signature

Verify Standard Webhooks

Rotating the secret

Express handler

Check that Hookie sent it (Web Bot Auth)

Notes

​The headers

​Two schemes, one secret

​Verify Hookie-Signature

​Verify Standard Webhooks

​Rotating the secret

​Express handler

​Check that Hookie sent it (Web Bot Auth)

​Notes

The headers

Two schemes, one secret

Verify Hookie-Signature

Verify Standard Webhooks

Rotating the secret

Express handler

Check that Hookie sent it (Web Bot Auth)

Notes