# Khipu Webhooks

## 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)

```javascript
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)

```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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/khipu-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/khipu-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/khipu-webhooks/examples/fastapi/).

## Payload

| Field | Description |
| --- | --- |
| `payment_id` | Khipu payment identifier |
| `receiver_id` | Collecting account id |
| `subject`, `amount`, `discount`, `currency` | Payment details (amounts may arrive as numbers or strings) |
| `payer_name`, `payer_email`, `personal_identifier` | Payer details |
| `bank`, `bank_id`, `bank_account_number`, `payment_method` | How it was paid |
| `transaction_id`, `authorizer_operation_code` | Reconciliation references |
| `out_of_date_conciliation`, `conciliation_date` | Reconciliation info |
| `receipt_url` | PDF receipt |

See [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/khipu-webhooks/references/overview.md). Full reference: [Khipu payment webhook](https://docs.khipu.com/en/payment-solutions/instant-payments/payment-webhook).

## Environment Variables

```bash
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

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

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/khipu-webhooks/references/overview.md) - What Khipu sends and when
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/khipu-webhooks/references/setup.md) - Creating a collection with `notify_url`, finding the secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/khipu-webhooks/references/verification.md) - Signature details, test vector, gotchas