ascend-webhooks

Ascend Webhooks

Ascend (insurance payments / premium financing) sends webhooks so your app is notified when an event happens — for example when an invoice is paid. Ascend POSTs a JSON payload over HTTPS and signs it with an HMAC-SHA256 signature you must verify before trusting the event.

When to Use This Skill

• How do I receive Ascend webhooks?
• How do I verify Ascend webhook signatures?
• How do I parse the X-Ascend-Signature header?
• How do I handle invoice.paid (or payout / refund) events?
• Why is my Ascend webhook signature verification failing?

How Ascend Signs Webhooks

Ascend uses a custom Stripe-style HMAC-SHA256 scheme (not Svix, not Standard Webhooks). Two headers are sent:

Header	Example	Purpose
X-Ascend-Signature	t=1696200697,v1=5257a869e7...	Timestamp + HMAC signature
X-Ascend-Request-Timestamp	1696200697	Same Unix timestamp (redundant)

The signature is verified by:

1. Parse X-Ascend-Signature into t (timestamp) and v1 (hex HMAC).
2. Build the signed string as `${t}:${rawBody}` — the timestamp, a colon, then the raw request body.
3. Compute HMAC-SHA256(signed_string, webhook_secret) and hex-encode it.
4. Constant-time compare against v1.

Use the raw request body. Re-serializing the parsed JSON (key reordering, whitespace) changes the bytes and breaks the signature. There is no official Ascend SDK, so every framework below verifies manually.

Verification (core)

const crypto = require('crypto');

// Verify Ascend's "t=<timestamp>,v1=<hex>" signature over "<timestamp>:<rawBody>".
function verifyAscendSignature(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((p) => p.split('=').map((s) => s.trim()))
  );
  const { t: timestamp, v1: signature } = parts;
  if (!timestamp || !signature) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}:${rawBody}`) // colon separator + RAW body
    .digest('hex');

  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expected, 'hex')
    );
  } catch {
    return false; // length mismatch = invalid
  }
}