Event catalogue

Konsole offers 72 event types to subscribe to. 68 of them actually reach an endpoint, and the four that do not are named at the bottom of this page. Almost all of them arrive in the same envelope, described in Webhooks; only data changes from one to the next, and data is always the full resource, identical to what the REST endpoint for that resource returns. The exception is the Sync connection lifecycle, which has its own format.

This page is the complete list, grouped by what the event is about, with the thing worth doing when it lands.

How an endpoint decides to fire

Subscription matching is a plain string comparison against the events array you registered. Three cases, and no fourth.

Prefix wildcards do not exist. payment.* is a literal string that no event is ever equal to. If you want everything under one resource, list its types.

How the names are built

resource.verb, verb in the past tense, both lowercase. The verbs are stable across resources, which makes the list shorter to remember than it looks.

Three spellings cost people an afternoon: it is succeeded, never completed or complete; it is cancelled with two l; and Sync uses deauthorized with a z while everything else in the platform is British spelling.

Payments

The six states a payment moves through, and the attempt that fails without ending it. Only payment.succeeded means money.

payment.failed carries failure_reason in data. The field is absent, not null, when there is no reason to give.

An attempt refused at once

payment.attempt_failed is not an end. A provider refused one attempt on the spot, or no provider could take it, and the payment went back to pending: the payer can try again on the same payment. payment.processing may already have reached you for that attempt, and this is what follows it. A refusal that comes later, from the operator, ends the payment with payment.failed.

data is the payment, plus an attempt object:

"attempt": {
  "failure_code": "insufficient_funds",
  "failure_message": "Insufficient funds.",
  "channel": "cm.mtn"
}

failure_code is the provider's decline code when it gave one, no_eligible_provider when no provider could take the attempt, and payment_declined otherwise. In sandbox, a number ending in 000001 sends it.

Sandbox sends what live sends

A payment that reaches expired sends payment.expired, and one that reaches cancelled sends payment.cancelled, in sandbox as in live. A sandbox timeout used to send payment.failed and a sandbox cancellation nothing at all, so a handler tested in sandbox missed every live expiry.

Payment splits

Emitted when a single payment is debited in several instalments, using split_count or split_amounts on POST /payments/{id}/splits.

data is the full payment, plus a split object naming which instalment this was.

"split": {
  "id": "splt_9mWvL2xR7tB5nY4hC6dF",
  "split_number": 2,
  "amount": 500000,
  "currency": "XAF",
  "split_currency": "XAF",
  "status": "succeeded",
  "reference": "order-4172-2",
  "provider_reference": "MP260115.1032.B41209",
  "initiated_at": "2026-01-15T10:32:04+00:00",
  "succeeded_at": "2026-01-15T10:32:41+00:00"
}

The parent payment reaches payment.succeeded only once every instalment has succeeded, or once you close it with POST /payments/{id}/close. Counting payment.split.succeeded yourself to decide the order is complete is a way to ship an order that is half paid.

Live sends them for the same calls, on Mobile Money channels. The parent payment also sends payment.processing each time a tranche goes to the payer, and is partial between two tranches. Neither live nor sandbox splits a payment on its own: a single charge above the per-transaction cap of Limits is refused with a 422, and POST /payments/{id}/splits pays it in tranches. Split payments has what each call returns.

Refunds

data.transaction is the id of the payment being refunded, as a string, not a nested object.

Transfers

Payouts out of your balance, whether to a mobile money wallet, a bank account or a card.

Customers

The payload of customer.deleted is the customer after anonymisation: the name reads Deleted User <pseudonym>, and the email, phone and date of birth are gone. If you need the original values for your own records, you must have kept them.

Beneficiaries

data for the two receivable events is the debt itself: id, beneficiary, reference, refund, currency, amount, recovered, outstanding, status, settled_at and created_at, amounts in major units. See the receivables endpoint.

Payment links

A payment made through a link emits payment.*, not link.*. The link events are about the link object itself.

link.expired appears in the Konsole picker but is not delivered to account endpoints. Subscribing to it on an account endpoint produces nothing.

Invoices

Disputes

Chargebacks and complaints. These are the events with the shortest deadlines attached to them.

Accounts, for Sync platforms

These describe a connected merchant on a Sync platform, not your own account. The ones sent by the API arrive in the usual envelope:

Every one of them names its connection in data.account: the acc_… id, the value you send as X-Sync. Read the connection there, not in data.id, which is not always the connection:

On these events account is the id itself, a string. On the copy of a payment, refund, transfer or dispute event a platform receives, and on fee.received, account is an object and the id is in account.id: see Sync platforms receive a copy.

There is no account.deleted. account.created announces the invitation you created; the merchant's acceptance is account.connected, below. When the merchant revokes the connection themselves, the account.deauthorized you receive is the Sync-format one.

The rest of the connection's life, and the same changes when they are made from the Dashboard rather than the API, are sent in the Sync format described in the next section:

Sync lifecycle deliveries

The events of the second table do not travel like the others. They are sent to the endpoints of the platform that owns the connection, in the environment of that connection.

• Only an exact subscription receives them. * and an empty events array do not match. List each type you want.
• The body is flat, not the usual envelope: event, account (the connection's acc_… id), sandbox, timestamp, then the fields of that event. There is no data: read the connection in account, the key the API's own account.* events use under data. sync_uid carries the same acc_… id and stays for the platforms that already read it. Rely only on the fields documented here.
• The headers are different: X-Sync-Event names the event, X-Idempotency-Key identifies the delivery, and X-Sync-Signature-V1 with X-Sync-Timestamp carry the signature.
• Verify the signature as for any other delivery. X-Sync-Signature-V1 is v1= followed by the hex HMAC-SHA256 of {timestamp}.{raw_body}, keyed with the endpoint's signing secret, and X-Sync-Timestamp is that timestamp in Unix seconds. Pass both to constructEvent in the SDKs, or verify them by hand as in Signature verification, and refuse a delivery whose timestamp is more than 300 seconds from your clock. Then record each X-Idempotency-Key you have processed, and ignore a delivery whose key you have already seen.
• X-Sync-Signature is kept for existing integrations. It is the HMAC-SHA256 of the raw body alone, in hexadecimal with no v1= prefix. It does not sign the time, so it cannot tell a replay from a delivery. It will be retired later: verify X-Sync-Signature-V1 instead.
• Retries are short: three attempts, 30 seconds then 2 minutes apart, 10 seconds each. These deliveries do not appear in the Konsole event log.

This is what account.connected looks like:

Balance and fees

balance.updated sends the movement itself, which is what you want for a ledger.

The eight figures GET /balance returns are not in this payload. Call the endpoint when you need the totals.

Compliance

Emitted while your account is being verified, and whenever your file changes state afterwards.

For a platform onboarding merchants, compliance.verified is the signal that a connected account may start taking live payments. Do not infer it from anything else.

Providers

Emitted when the set of rails available to your account changes.

Worth subscribing to if you cache your account's channels rather than calling GET /providers on every checkout.

Webhook endpoints

Useful on a platform account where several people can change the configuration. Note that the endpoint receiving this event may be the one that was just changed.

What data actually contains

data is the resource serialised by the same code that serves the REST endpoint, with three consequences worth knowing.

A field with no value is absent or null, depending on the resource. A payment or a customer drops it: a payment with no description has no description key at all. A transfer, an invoice, a link or an account sends it as null. Read every field with a default, and accept null.

An empty object stays an object. A metadata with nothing in it arrives as {}, as the REST endpoint returns it, never as [], so a handler that reads it into a map or a struct does not break on the empty one.

The payload is always in the latest API version. Version pinning applies to your API calls, not to webhook deliveries: the envelope's api_version is the platform's current version at the moment the event was recorded, and the body is shaped for that version. Pinning your account to 2026-08-01 does not change what your endpoint receives.

Events people look for and do not find

Events Wajub records for its own use are never delivered, even to * subscribers.

Types you can subscribe to that never arrive

Konsole lets you tick this one. Nothing is ever delivered.

payment.checkout_page_opened and payment.redirected_to_callback were offered too, and never delivered either: they are checkout timeline entries, recorded in the Konsole event log only. They are no longer offered. An endpoint that already lists one keeps it, without effect, and can still be saved with it. Both stay visible in Events, so you can still audit a checkout after the fact.

Sandbox and live are separate streams

An endpoint belongs to one environment. A sandbox endpoint only ever receives sandbox events, and a live endpoint only live ones. Two things change in the payload:

• livemode is false in sandbox and true in live.
• Event ids are prefixed evt_test_ in sandbox and evt_ in live.

A handler that hardcodes an id length or slices a prefix off will break when it meets the other environment.

Sync platforms receive a copy

When a payment, refund or transfer belongs to a merchant connected through Sync, or a dispute is opened on such a payment, the event is delivered twice: once to the merchant's own endpoints, and once to the platform's, as a separate event with its own id. The platform's copy carries an extra account object so you know which connected merchant it came from. Links, invoices and beneficiaries the connection created are not copied: GET /events with X-Sync lists their events.

"account": {
  "id": "acc_7Yh2MpL4tRb3nP8sZcXv",
  "reference": "boutique-akwa"
}

Deduplicate on the event id, not on the payment id: the two copies describe the same payment and carry two different event ids, deliberately.