alipay-webhooks

Alipay Webhooks

Alipay's global / cross-border products — Antom (Cashier Payment / AMS) and Alipay+ — deliver asynchronous webhook notifications (notifyPayment, notifyRefund, notifyCapture, notifyAuthorization, notifyDispute) signed with an asymmetric RSA256 (SHA256withRSA) scheme carried in a Signature header. This skill targets that header-based scheme.

Legacy note: The older Alipay openapi / MAPI integration (openapi.alipay.com, global.alipay.com) is a different, unrelated scheme — form-encoded params with sign + sign_type=RSA2, verified by stripping sign/sign_type, sorting the remaining params A–Z, joining with &, and replying with the plain text success. If your integration posts application/x-www-form-urlencoded bodies with a sign field, you are on that older vintage — this skill does not cover it. Everything below is the modern Antom/Alipay+ header RSA256 scheme.

When to Use This Skill

• How do I receive Alipay / Antom / Alipay+ webhooks?
• How do I verify the Alipay Signature header (RSA256 / SHA256withRSA)?
• How do I handle notifyPayment, notifyRefund, or notifyDispute events?
• Why is my Alipay webhook signature verification failing (base64URL encoding)?
• How do I sign the acknowledgement response Antom expects?

Verification (core)

Alipay/Antom signs each request with SHA256withRSA using its private key and carries the result in a Signature header. You verify it with Antom's public key (from the Dashboard). Three details trip people up:

1. The signed content is exactly two lines: <METHOD> <URI> then <Client-Id>.<Request-Time>.<RawBody> joined by single periods.
2. The signature is base64URL encoded (URL-safe alphabet), and is often additionally percent-encoded on the wire — URL-decode, then base64-decode.
3. Use the raw request body — never re-serialize parsed JSON first.

const { createVerify } = require('crypto');

// Header: "algorithm=RSA256,keyVersion=1,signature=<urlEncoded base64url sig>"
function parseSignatureHeader(header) {
  return Object.fromEntries(
    header.split(',').map((p) => {
      const i = p.indexOf('=');
      return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
    })
  );
}

function verifyAlipay({ method, uri, clientId, requestTime, rawBody, signatureHeader, publicKey }) {
  const { signature } = parseSignatureHeader(signatureHeader);
  if (!signature) return false;
  const content = `${method} ${uri}\n${clientId}.${requestTime}.${rawBody}`;
  // Percent-decode, normalize URL-safe base64 → standard, then decode.
  const sig = Buffer.from(decodeURIComponent(signature).replace(/-/g, '+').replace(/_/g, '/'), 'base64');
  const v = createVerify('RSA-SHA256');
  v.update(content, 'utf8');
  v.end();
  try {
    return v.verify(publicKey, sig); // publicKey = Antom/Alipay+ PEM public key
  } catch {
    return false;
  }
}