Webhooks

Configuring your endpoint

Set your webhook URL and choose which events to subscribe to from the Merchant Portal's Webhooks page — generate a signing secret there too (shown once, like an API key), and use the page's Send Test Webhook button to confirm your endpoint is reachable before going live. The same page shows the status of your most recent delivery attempt.

Event types

The events below are the ones your integration should actually handle. A few additional names are reserved in the schema for features on the roadmap (refunds, chargebacks, scheduled sweeps) — you'll see them in the enum, but nothing emits them yet.

Status lifecycle

The status field on a collection webhook (and on GET /v1/collections/{id}) is always one of these seven values:

Payload shape

{
  "event": "collection.successful",
  "merchant_code": "27048391",
  "collection_id": "col_xxxxx",
  "transaction_id": "txn_xxxxx",
  "reference": "ORDER-4821",
  "merchant_reference": "ORDER-4821",
  "amount": 50000,
  "fee": 750,
  "net_amount": 49250,
  "currency": "TZS",
  "status": "successful",
  "timestamp": "2026-08-23T10:00:00+03:00"
}

merchant_code is your Merchant ID — identification only, never a secret and never usable as an API key. reference and merchant_reference are the same value — kept as two keys so existing integrations parsing reference keep working.

fee/net_amount are only present once a fee has actually been calculated (i.e. from collection.successful/collection.reversed onward) — never fabricated for an event where no fee exists yet.

Verifying a delivery

Every delivery is signed with your merchant's webhook secret, sent as X-Infinity-Signature: an HMAC-SHA256 hex digest of the exact raw request body. Recompute it and compare — don't trust a delivery that doesn't match, and use a constant-time comparison to avoid leaking timing information.

import hashlib
import hmac

def verify_signature(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

const crypto = require("crypto");

function verifySignature(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(signature || "", "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express example — read the raw body BEFORE any JSON-parsing middleware
// runs, since the signature is computed over the exact raw bytes:
app.post(
  "/api/infinity/webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.header("X-Infinity-Signature");
    if (!verifySignature(req.body, signature, process.env.INFINITY_WEBHOOK_SECRET)) {
      return res.status(401).send("invalid signature");
    }
    const event = JSON.parse(req.body);
    // ... handle event.event / event.status / event.collection_id
    res.status(200).send("ok");
  },
);