Webhooks and events

Each gateway calls a route in your app when something happens. You pass that request to callCash, and your handler gets one event shape, already checked with the gateway.

One route per gateway#

// app/api/yoco/webhook/route.ts
export async function POST(req: Request) {
  const r = await cash.webhooks.handle("yoco", req, onCash);
  return r.response;
}

// app/api/netcash/notify/route.ts
export async function POST(req: Request) {
  const r = await cash.webhooks.handle("netcash", req, onCash);
  return r.response;
}

Always return r.response as it is. Its status tells the gateway whether to send the notification again.

One handler#

// lib/on-cash.ts
import type { CashEvent } from "callcash";

export async function onCash(event: CashEvent) {
  switch (event.type) {
    case "payment.paid":
      await markOrderPaid(event.reference, event.amount); // must be safe to run twice
      break;
    case "payment.failed":
      await markOrderFailed(event.reference, event.reason);
      break;
    case "payment.mismatch":
      await alertSomeone(event.reference, event.reason);  // do not fulfil
      break;
  }
}

What is checked before your handler runs#

Every event your handler receives has verified: true.

Events#

The event object#

Exactly once#

• The same notification sent twice produces one event.
• Two notifications arriving at the same moment still run your handler once: an event is claimed while your handler runs. A claim lapses after a minute, so a crashed process does not strand the event.
• Even so, write your handler to be safe to run twice for the same event.id. Networks and processes fail in ways no library can rule out.

When your handler throws#

1. The payment is still recorded.
2. The gateway gets a 500, so it sends the notification again.
3. The event stays owed. It comes back with the same id and redelivery: true.

Do not catch and hide errors inside your handler. Throwing is how the retry happens.

A safety net: deliver what is owed#

const { delivered, failed } = await cash.events.deliver(onCash);

This hands every event still owed to your handler. Run it from a cron job, or after your handler has been down. One payment failing does not stop the rest.

The result of handle()#

Responses handle can give:

Running beside older payment code#

When handled is false, the notification belongs to something callCash did not create, such as checkouts your old code opened. Pass it on:

export async function POST(req: Request) {
  const r = await cash.webhooks.handle("yoco", req.clone(), onCash);
  if (r.handled) return r.response;
  return oldYocoHandler(req); // unchanged
}

Use req.clone() so the old code can still read the body.

Listing events#

const events = await cash.events.list({ after: "evt_…", limit: 100 });

Oldest first. after continues from an event id.

Who retries, and for how long#

Today callCash runs inside your server, so callCash doesn't send you webhooks. Yoco and Netcash send them to your routes, and cash.webhooks.handle() checks each one before your handler sees it.

• If your handler throws, we answer the gateway with a 500. The gateway sends the notification again on its own retry schedule, which belongs to Yoco or Netcash, not to us. The event keeps its id and arrives with redelivery: true.
• If the gateway gives up, the event is still owed in your store. Run cash.events.deliver(onCash) from a cron, every few minutes, and nothing is lost.
• The hosted service is planned. It will send its own webhooks, and its retry window and schedule will be published here before it handles a payment.

When the money arrives#

callCash never holds money, so settlement is between your gateway and your bank, on the gateway's payout terms. Check your Yoco or Netcash agreement for when payouts happen. A payment.paid event means the gateway confirmed the payment. It doesn't mean the money has reached your bank yet.