Kopo Kopo API Webhooks Explained for Non-Developers

A webhook is a phone call between systems. When a customer pays your till, Kopo Kopo doesn't wait for anyone to check anything — it calls your POS and says, 'KES 1,500 just landed on till 3502582, from a number ending in 123.' No developer required to understand that. This guide explains the whole idea over the counter.

You'll come away knowing the two halves of any webhook — the event and the delivery — why the call carries a signature, what your till does with it, and what breaks when webhooks aren't set up.

1. A Webhook Is Just a Phone Call

Every webhook has two halves. The event: what happened — a payment arrived, with its amount and its details. The delivery: how your till finds out — Kopo Kopo dials a callback URL your POS registered when you subscribed till webhooks.

• Who calls — Kopo Kopo, the moment the money moves.
• Who picks up — your POS, at the callback URL wired up during setup.
• What's said — a payment event: amount, till number, paying number, time.
• How you know it's genuine — a signature on the call.

2. The Signature Is What Makes It Trustworthy

The key word is signed. Kopo Kopo signs every payment notification with a secret only it and your POS share — carried in the X-KopoKopo-Signature header. Before the till closes a sale on the strength of a call, it checks the signature. Wrong signature, ignored.

Why that matters at the counter: the 'I paid' claim. A customer or a staff member cannot forge a confirmation. The only way a sale closes as paid is if Kopo Kopo itself confirmed the payment.

3. What the Till Does with the Call

• Matches it to an open sale — by amount, and by the paying number where available.
• Closes the sale — receipt, stock drop, and a payment line in the shift record.
• Or holds it — no match yet means the payment stays visible until a cashier resolves it. Nothing vanishes.

That's the whole magic: nobody checks anything, because the system that knows about the money is the system that tells the till.

4. Two Calls Your Till Cares About

In a shop, two Kopo Kopo webhooks matter, and both run through the same integration:

• Payment received — a customer paid a till (buy goods). Kiosk uses it to complete sales, including the 'listening for till payment' flow where the cashier keeps working while the customer pays.
• Send money — a payout was confirmed (Kopo Kopo Send Money). Kiosk uses it to update supplier ledgers the moment you pay an invoice.

One integration, two directions — money in and money out — and both update your records automatically.

5. Webhooks vs. Checking Messages

6. Why This Matters at Close

Because every payment arrived signed and matched at the moment it happened, the end-of-day report is a formality: the M-Pesa column comes from confirmed payments, and it agrees with your business account. Reconciliation doesn't disappear — it shrinks to the exceptions, and most days there are none.

Read next:

• Kopo Kopo Integration for POS Systems: The Complete GuideThe pillar guide — how the whole integration fits together.→
• How to Connect Kopo Kopo to Your POS SystemThe step-by-step setup, including subscribing till webhooks.→
• End-of-Day Reconciliation: Manual vs. AutomatedWhat the close looks like when every payment already matched itself.→
• Why Your M-Pesa Payments Aren't Syncing with Your Sales RecordsThe common causes — unsubscribed tills among them.→
• Kiosk.ke's Kopo Kopo IntegrationThe deep-dive on how Kiosk uses payment and Send Money webhooks.→