> ## Documentation Index > Fetch the complete documentation index at: https://docs.kwugwo.africa/llms.txt > Use this file to discover all available pages before exploring further. # Webhook events > Every event Kwugwo sends, when it fires, and what its payload contains. Every delivery wraps one object in the same [envelope](https://docs.kwugwo.africa/webhook-deliveries.md#the-event-object). `data` has the same fields as the corresponding API object, with the additions noted below. ## Which events to handle | If you want to… | Subscribe to | | - | - | | Fulfil paid orders | `ugwo.successful` | | Tell the customer an attempt failed or expired | `ugwo.activity.updated` | | Catch customers who paid twice | `ugwo.activity.double_charge_detected` | | Update a custom payment UI step by step | `ugwo.activity.next_action.created`, `ugwo.activity.next_action.updated` | | Track refunds | `refund.successful`, `refund.failed` | | Sync customers to your CRM | `nzube.onye.created`, `nzube.onye.updated`, `nzube.onye.deleted` | > [!NOTE] > > Several events can describe the same change: the broad `*.updated` > event, plus a specific one such as `*.successful`. Run business logic > on the specific event and treat `*.updated` as an audit feed. > Deliveries can arrive out of order; decide based on `data.status`, > not arrival order. ## All events | Event | Fires when | `data` | | - | - | - | | `ugwo.created` | An ugwo is created. | [Ugwo](#ugwo-events) | | `ugwo.updated` | Any field of an ugwo changes, e.g. `status`. | [Ugwo](#ugwo-events) | | `ugwo.successful` | An ugwo becomes `ugwo_successful` (paid in full). | [Ugwo](#ugwo-events) | | `ugwo.activity.created` | A payment attempt starts. | [Activity](#activity-events) | | `ugwo.activity.updated` | Any field of an activity changes. | [Activity](#activity-events) | | `ugwo.activity.successful` | An attempt succeeds. | [Activity](#activity-events) | | `ugwo.activity.double_charge_detected` | An attempt succeeds on an ugwo that was already paid. | [Activity](#activity-events) | | `ugwo.activity.next_action.created` | A next action is attached to an activity. | [Next action](#next-action-events) | | `ugwo.activity.next_action.updated` | A next action becomes `fulfilled` or `expired`, or records a `last_error`. | [Next action](#next-action-events) | | `refund.created` | A refund is recorded (including ones made in the PSP dashboard). | [Refund](#refund-events) | | `refund.updated` | Any field of a refund changes. | [Refund](#refund-events) | | `refund.successful` | The PSP confirms the refund. | [Refund](#refund-events) | | `refund.failed` | The refund is rejected. | [Refund](#refund-events) | | `nzube.onye.created` | A customer is created (including via `onye_email`). | [Customer](#customer-events) | | `nzube.onye.updated` | A customer changes. | [Customer](#customer-events) | | `nzube.onye.deleted` | A customer is deleted. | [Customer](#customer-events) | ## Ugwo events `data` is an [Ugwo object](https://docs.kwugwo.africa/ugwo/object.md) **including** `lastest_ugwo_activity` (spelled with the extra `t`). ```json ugwo.successful theme={"system"} { "uid": "evt.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE", "event": "ugwo.successful", "data": { "uid": "ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE", "ref": "order_4719", "onye_nzube": { "uid": "ony.VCvr.Qm3kTn8XcBd5RyWkJhZsAuLp", "email": "ada@example.com", "first_name": "Ada", "last_name": "Okeke", "nzube_ref": "user_8821", "billing_address": null, "created_at": "2026-05-10T08:00:00+00:00", "updated_at": "2026-05-10T08:00:00+00:00", "meta": {}, "total_successful_activities": 3, "total_failed_activities": 0, "latest_ugwo_activity": "act.VCvr.qnbBJaElzSTHOcaTzxbuDlIs" }, "amount": 500000, "currency": "NGN", "status": "ugwo_successful", "description": "Order #4719", "created_at": "2026-05-15T09:14:22+00:00", "updated_at": "2026-05-15T09:21:40+00:00", "checkout": { "uid": "chk.VCvr.vBtGwathtd99FpQGIGwIAATX", "currency": "NGN", "mediums": [{ "medium": "bank_transfer" }, { "medium": "ussd" }] }, "lastest_ugwo_activity": { "uid": "act.VCvr.qnbBJaElzSTHOcaTzxbuDlIs", "activity_type": "charge", "status": "successful", "amount": 500000, "charged_amount": 500000, "...": "see Activity events" }, "total_amount_paid": 500000, "fee": 0, "meta": { "order_id": "4719" } }, "changed_fields": null, "created_at": "2026-05-15T09:21:40+00:00" } ``` On `ugwo.updated`, `changed_fields` holds the previous values, e.g. `{ "status": "processing", "total_amount_paid": 0 }`. ## Activity events `data` is an [Activity object](https://docs.kwugwo.africa/ugwo/activity-object.md) plus two fields pointing at its parent payment: **ugwo\_uid** `string` The parent ugwo ID. **ugwo** `string` The parent ugwo ID (same value). ```json ugwo.activity.updated theme={"system"} { "uid": "evt.VCvr.Ts9mLq2WxPn4KdRb7VcHyZeA", "event": "ugwo.activity.updated", "data": { "uid": "act.VCvr.qnbBJaElzSTHOcaTzxbuDlIs", "activity_type": "charge", "checkout": { "uid": "chk.VCvr.vBtGwathtd99FpQGIGwIAATX", "currency": "NGN", "mediums": [{ "medium": "bank_transfer" }, { "medium": "ussd" }] }, "ugwo_medium": null, "psp": "paystack_ng", "psp_external_id": "5kfxw34ugz", "status": "expired", "created_at": "2026-05-14T19:55:50+00:00", "error": null, "updated_at": "2026-05-14T20:10:51+00:00", "amount": 500000, "nzube_subscription_charge": 2500, "refunded_amount": 0, "charged_amount": 0, "next_action": { "uid": "uac.VCvr.Rk4mZpQ7wLsD2vT8xNbHyCeU", "action": { "type": "user_action", "instruction": "Transfer to bank", "headers": { "...": "..." } }, "status": "expired", "last_error": null, "expires_at": "2026-05-14T20:10:50+00:00", "created_at": "2026-05-14T19:55:51+00:00", "updated_at": "2026-05-14T20:10:51+00:00" }, "is_double_charge": false, "ugwo_uid": "ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE", "ugwo": "ugw.VCvr.7K2qPmRtV9xLnQ8sD1cYwHfE" }, "changed_fields": { "status": "requires_action", "next_action": { "status": "pending" } }, "created_at": "2026-05-14T20:10:51+00:00" } ``` ### Double charge detected Same payload, with `is_double_charge: true` and `status: "successful"`. The customer paid an ugwo that was already paid; its status doesn't change. [Refund](https://docs.kwugwo.africa/refunds/create.md) this activity. ## Next action events `data` is a [Next action object](https://docs.kwugwo.africa/ugwo/next-action-object.md). It doesn't reference its activity, so match it by the `next_action.uid` you saw on the activity, or re-fetch the activity you're tracking. ```json ugwo.activity.next_action.created theme={"system"} { "uid": "evt.VCvr.Wq3nRt8KpXz5LmVb2DcHyFeS", "event": "ugwo.activity.next_action.created", "data": { "uid": "uac.VCvr.Mw5rTq8NcXz2LpVb7KdHyFeJ", "action": { "type": "input_otp", "supports_resend": true }, "status": "pending", "last_error": null, "expires_at": "2026-08-12T10:34:41+00:00", "created_at": "2026-08-12T10:24:41+00:00", "updated_at": "2026-08-12T10:24:41+00:00" }, "changed_fields": null, "created_at": "2026-08-12T10:24:41+00:00" } ``` ## Refund events `data` is a [Refund object](https://docs.kwugwo.africa/refunds/object.md). Its `ugwo_activity` also carries `ugwo_uid` and `ugwo`. See [Refund webhooks](https://docs.kwugwo.africa/refunds/webhooks.md) for handling. ## Customer events `data` is a [Customer object](https://docs.kwugwo.africa/customers/object.md), with `latest_ugwo_activity` as an activity ID. ```json nzube.onye.created theme={"system"} { "uid": "evt.VCvr.Bn6tYq1MzRx8KpLc3WvHdFgJ", "event": "nzube.onye.created", "data": { "uid": "ony.VCvr.Qm3kTn8XcBd5RyWkJhZsAuLp", "email": "ada@example.com", "first_name": null, "last_name": null, "nzube_ref": null, "billing_address": null, "created_at": "2026-05-15T09:14:22+00:00", "updated_at": "2026-05-15T09:14:22+00:00", "meta": {}, "total_successful_activities": 0, "total_failed_activities": 0, "latest_ugwo_activity": null }, "changed_fields": null, "created_at": "2026-05-15T09:14:22+00:00" } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.