Event catalogue

Every event Wajub sends, grouped by what it is about, with what to do when it lands. All of them arrive in the webhook envelope with the full resource in data, except the Sync lifecycle deliveries, which have their own format.

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. From API version 2026-10-12, registering payment.*, or any name that is not an event type, answers 422; on earlier versions it is stored as a literal string that no event is ever equal to. If you want everything under one resource, list its types, copied from this page.

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. On a channel that takes a code the payer generates, it is also sent when that code is missing (otp_required) or refused (invalid_otp, and otp_attempts_exceeded the third time); other refusals keep the provider's code. The operator refusing that code later sends payment.attempt_failed too, not payment.failed.

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 is replaced, 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. A link's own endpoints, set in its Webhooks tab, also get its payments, tickets, gifts, orders and refunds: see Webhooks of one link.

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. 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.
• Only a 2xx is a delivery, as for every other event: a redirect is not followed and counts as a failure. Each attempt goes to the endpoint as it is when it is sent, signed with its current secret, and an endpoint disabled or deleted in the meantime is sent nothing more.
• Redelivery lasts only a few minutes: keep the endpoint up and answer within 10 seconds. 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 totals GET /balance returns are not in this payload. Call the endpoint when you need them.

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 as its REST endpoint returns it. Three things are worth knowing.

A field with no value can be absent or null. Read every field with a default, and accept null.

An empty metadata arrives as {}, never as [].

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

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.