smile-webhooks

Smile API Webhooks

Smile API (getsmileapi.com) is an employment, income, and financial-data aggregator for Southeast Asia (Philippines-focused). It POSTs JSON webhooks to your HTTPS endpoint when a user connects an account, a task finishes, or new data is added. Each delivery carries a Smile-Signature header you verify with HMAC-SHA512 (hex) over the raw request body.

Not Smile.io (loyalty/rewards) and not Smile Identity (KYC). The signature header is Smile-Signature (no X- prefix) and the algorithm is SHA-512, not SHA-256. Smile does not use the Standard Webhooks spec.

When to Use This Skill

• How do I receive Smile API (getsmileapi.com) webhooks?
• How do I verify the Smile-Signature header?
• Why is my Smile webhook signature verification failing?
• How do I handle ACCOUNT_CONNECTED, TASK_FINISHED, or INCOMES_ADDED events?
• How do I dedupe Smile webhook retries?

Verification (core)

Smile computes HMAC-SHA512(secret, rawBody) and hex-encodes it. The secret is the per-endpoint value you set when registering the webhook (1–64 chars). Digest the entire raw body with no leading/trailing whitespace — never the re-serialized parsed JSON. Compare in constant time.

const crypto = require('crypto');

// Verify the Smile-Signature header: HMAC-SHA512 hex over the RAW request body.
function verifySmileSignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha512', secret)
    .update(rawBody) // Buffer/raw string — NOT JSON.stringify(parsed)
    .digest('hex');
  const received = Buffer.from(String(signatureHeader || ''), 'utf8');
  const computed = Buffer.from(expected, 'utf8');
  // timingSafeEqual throws on length mismatch — guard first.
  return (
    received.length === computed.length &&
    crypto.timingSafeEqual(received, computed)
  );
}

Verify before parsing JSON, then dispatch on the type field. There is no official Smile SDK, so all three framework examples verify manually.