aftership-webhooks

AfterShip Webhooks

AfterShip (aftership.com) is the post-purchase platform. Four of its products send webhooks — Tracking (the flagship shipment-tracking product), Shipping (formerly Postmen), Returns, and Warranty. They all use the same HMAC algorithm but send the signature under three different header names.

When to Use This Skill

• How do I receive AfterShip webhooks?
• How do I verify AfterShip webhook signatures?
• What is the aftership-hmac-sha256 header and how do I validate it?
• Why is my AfterShip webhook signature verification failing?
• How do I handle tracking_update, edd_revise, or tracking_pending_time events?
• How do I route on msg.tag (InTransit, Delivered, Exception, …)?
• How do I verify AfterShip Returns (as-signature-hmac-sha256) or Shipping (am-webhook-signature) webhooks?

Verification (core)

One algorithm for every product: HMAC-SHA256 over the raw request body, keyed with the webhook secret as a UTF-8 string (do not base64-decode it), digest encoded as standard base64. Nothing else is signed — there is no timestamp header and no replay window, so do not add a tolerance check.

Only the header name differs:

Node:

const crypto = require('crypto');

// Checked in order; the prefix strip is harmless on the two bare headers.
const SIGNATURE_HEADERS = ['aftership-hmac-sha256', 'as-signature-hmac-sha256', 'am-webhook-signature'];

function verifyAfterShipSignature(rawBody, headers, secret) {
  if (!secret) return false; // fail closed — never skip verification
  const name = SIGNATURE_HEADERS.find((h) => headers[h]);
  if (!name) return false;
  const received = String(headers[name]).replace(/^hmac-sha256=/, '');
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('base64');
  const a = Buffer.from(received);
  const b = Buffer.from(expected);
  // Guard the length: timingSafeEqual throws when the buffers differ in size.
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}