Khipu Webhooks Skill

When to Use This Skill

• How do I receive Khipu webhooks (the notify_url of a collection)?
• How do I verify the x-khipu-signature header (t=...,s=...)?
• Why is my Khipu webhook signature verification failing?
• How do I handle a reconciled Khipu payment notification (payment_id, amount, conciliation_date)?

Only notifications API version 3.0 is supported. Version 1.3 notifications aren't signed this way and fail verification.

Khipu sends one POST to the collection's notify_url when a payment is reconciled, for collections created with notify_api_version "3.0". The older 1.3 API sent only a notification_token and is not covered here. The docs don't describe retries or an expected acknowledgement; answer 200 once the payment is recorded.

Essential Code (USE THIS)

Khipu signs every delivery:

x-khipu-signature: t=1711965600393,s=rq08YUGSaWa1D0RAwhMnJTRHMNmY4ToCn2Gd6G9LaDg=

• t is a Unix timestamp in milliseconds. Use it as the exact string from the header.
• s is standard padded base64 of HMAC-SHA256 over "<t>.<raw body>". The key is the merchant secret of the collecting account, as UTF-8 bytes (not decoded).
• There is no event-name field or header: every POST is a reconciled payment.

Verification (Node.js)

const crypto = require('crypto');

// rawBody: Buffer of the exact request bytes (express.raw({ type: '*/*' }), not express.json)
function verifyKhipu(rawBody, header, secret) {
  if (!secret || !header) return false;
  let t;
  const sigs = [];
  for (const item of header.split(',')) {
    const i = item.indexOf('=');
    const key = item.slice(0, i).trim(), value = item.slice(i + 1).trim();
    if (key === 't' && t === undefined) t = value;
    else if (key === 's') sigs.push(value);
  }
  if (!t) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('base64');
  return sigs.some((s) => {
    if (!/^[A-Za-z0-9+/]{43}=$/.test(s)) return false; // validate before comparing, never Buffer.from(s, 'base64')
    const a = Buffer.from(s), b = Buffer.from(expected);
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

Verification (Python)

import base64, hashlib, hmac, re

def verify_khipu(raw_body: bytes, header, secret: str) -> bool:
    if not secret or not header:
        return False
    t, sigs = None, []
    for item in header.split(","):
        key, _, value = item.partition("=")
        key, value = key.strip(), value.strip()
        if key == "t" and t is None:
            t = value
        elif key == "s":
            sigs.append(value)
    if not t:
        return False
    digest = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).digest()
    expected = base64.b64encode(digest)
    return any(
        re.fullmatch(rb"[A-Za-z0-9+/]{43}=", s.encode()) and hmac.compare_digest(s.encode(), expected)
        for s in sigs
    )

Accept the delivery if any s= entry matches (the header can carry several during key rotation) and ignore other keys. A missing header, no t=, a malformed signature or a mismatch gets 401.

Timestamp window is off by default. Hookdeck retries and replays resend the original t, and Hookdeck applies no tolerance itself, so a fixed window would reject legitimate redeliveries. The examples offer an opt-in: set KHIPU_WEBHOOK_TOLERANCE_SECONDS to a positive number (t is milliseconds, the examples convert). Unset or 0 leaves it off. Use payment_id for idempotency instead.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Payload

See references/overview.md. Full reference: Khipu payment webhook.

Environment Variables

KHIPU_WEBHOOK_SECRET=your_merchant_secret      # the collecting account's secret
KHIPU_WEBHOOK_TOLERANCE_SECONDS=0              # optional; a positive value opts in to the replay window

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 khipu --path /webhooks/khipu

Reference Materials

• references/overview.md - What Khipu sends and when
• references/setup.md - Creating a collection with notify_url, finding the secret
• references/verification.md - Signature details, test vector, gotchas