quoter-webhooks

Quoter Webhooks

When to Use This Skill

• Setting up Quoter webhook handlers
• Debugging Quoter hash verification failures
• Understanding Quoter object types (Quote, Person, Payment) and create vs update
• Parsing the application/x-www-form-urlencoded hash / timestamp / data payload

⚠️ Security Warning: Weak Verification Scheme

Quoter does not use HMAC-SHA256, and it is not Standard Webhooks. It uses a legacy MD5 shared-secret hash, and the hash key is optional — a Quoter webhook can be configured with no verification at all.

• The signature is a form field named hash, not an HTTP header.
• Always set a hash key in Quoter (Settings → Integrations). Without one, anyone who learns your endpoint URL can forge requests.
• MD5 is cryptographically broken. Treat this as a low-assurance check and pair it with a network-level control (IP allowlist, a shared secret in the URL path, or fronting the endpoint with Hookdeck).

Verification (core)

Quoter POSTs application/x-www-form-urlencoded with three fields: hash, timestamp, and data. The data field is the JSON (or XML) payload as a string. Verify by computing md5(HASH_KEY + timestamp + data) and comparing to hash. Hash the data string exactly as received — never re-serialize the parsed JSON, or the hash won't match.

Node:

const crypto = require('crypto');

// timestamp and data come from the parsed form body (already URL-decoded).
function verifyQuoter(hashKey, timestamp, data, receivedHash) {
  if (!hashKey || !receivedHash) return false; // no hash key => reject (verification disabled)

  const expected = crypto
    .createHash('md5')
    .update(hashKey + timestamp + data)   // data is the raw JSON/XML string, unmodified
    .digest('hex');

  // Reject stale requests: timestamp is GMT UNIX seconds
  const fresh = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) <= 300;
  try {
    return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(receivedHash));
  } catch {
    return false; // length mismatch = invalid
  }
}