ebay-webhooks

eBay Webhooks

When to Use This Skill

• How do I receive eBay webhooks (notifications)?
• How do I pass eBay's endpoint challenge validation (challenge_code)?
• How do I verify the x-ebay-signature header (ECDSA)?
• How do I use the eBay getPublicKey endpoint and cache the public key?
• How do I handle MARKETPLACE_ACCOUNT_DELETION (marketplace account deletion / closure) notifications?
• Why is my eBay signature verification failing?

How eBay Webhooks Differ From Most Providers

eBay does not use HMAC with a shared secret, and does not follow the Standard Webhooks spec. Two distinct mechanisms are involved:

1. Endpoint challenge (one-time, on save) — When you register or update a destination, eBay sends GET https://<your-endpoint>?challenge_code=.... You must respond HTTP 200 with JSON {"challengeResponse":"<hex>"} where the hex is the SHA-256 hash of exactly `challengeCode + verificationToken
   • endpoint` — in that order. The order is mandatory.
2. Per-notification signature (ECDSA) — Every notification carries an x-ebay-signature header: a Base64-encoded JSON object with fields alg, kid, signature, and digest. Use the kid to fetch the matching public key via getPublicKey, then verify the ECDSA signature over the raw request body. Cache the public key ~1 hour (keyed by kid).

Verification (core)

Endpoint challenge — deterministic SHA-256, no crypto keys needed:

const crypto = require('crypto');

function challengeResponse(challengeCode, verificationToken, endpoint) {
  // ORDER IS MANDATORY: challengeCode + verificationToken + endpoint
  const hash = crypto.createHash('sha256');
  hash.update(challengeCode);
  hash.update(verificationToken);
  hash.update(endpoint);
  return hash.digest('hex'); // return as { challengeResponse: <hex> } with HTTP 200
}

Per-notification signature — ECDSA over the raw body, key fetched by kid:

async function verifyEbaySignature(rawBody, signatureHeader, getPublicKey) {
  if (!signatureHeader) return false;
  let sig;
  try { sig = JSON.parse(Buffer.from(signatureHeader, 'base64').toString('utf8')); }
  catch { return false; }              // { alg, kid, signature, digest }
  if (!sig.kid || !sig.signature) return false;
  const pem = await getPublicKey(sig.kid); // cache ~1h, keyed by kid
  const verifier = crypto.createVerify('sha1'); // eBay signs ECDSA with SHA-1
  verifier.update(rawBody);            // RAW body bytes — do not re-serialize
  verifier.end();
  try { return verifier.verify(pem, sig.signature, 'base64'); }
  catch { return false; }
}