Webhook events

Every delivery wraps one object in the same envelope. 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`

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.updated`	Any field of an ugwo changes, e.g. `status`.	Ugwo
`ugwo.successful`	An ugwo becomes `ugwo_successful` (paid in full).	Ugwo
`ugwo.activity.created`	A payment attempt starts.	Activity
`ugwo.activity.updated`	Any field of an activity changes.	Activity
`ugwo.activity.successful`	An attempt succeeds.	Activity
`ugwo.activity.double_charge_detected`	An attempt succeeds on an ugwo that was already paid.	Activity
`ugwo.activity.next_action.created`	A next action is attached to an activity.	Next action
`ugwo.activity.next_action.updated`	A next action becomes `fulfilled` or `expired`, or records a `last_error`.	Next action
`refund.created`	A refund is recorded (including ones made in the PSP dashboard).	Refund
`refund.updated`	Any field of a refund changes.	Refund
`refund.successful`	The PSP confirms the refund.	Refund
`refund.failed`	The refund is rejected.	Refund
`nzube.onye.created`	A customer is created (including via `onye_email`).	Customer
`nzube.onye.updated`	A customer changes.	Customer
`nzube.onye.deleted`	A customer is deleted.	Customer

Ugwo events

data is an Ugwo object including lastest_ugwo_activity (spelled with the extra t).

ugwo.successful

{
  "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 plus two fields pointing at its parent payment:

string

The parent ugwo ID.

string

The parent ugwo ID (same value).

ugwo.activity.updated

{
  "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 this activity.

Next action events

data is a Next action object. 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.

ugwo.activity.next_action.created

{
  "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. Its ugwo_activity also carries ugwo_uid and ugwo. See Refund webhooks for handling.

Customer events

data is a Customer object, with latest_ugwo_activity as an activity ID.

nzube.onye.created

{
  "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"
}

Get started

Plugins

Guides

Concepts

API basics

Payments (Ugwo)

Activities

Next actions

Refunds

Customers (Onye)

Checkouts

Which events to handle

All events

Ugwo events

Activity events

Double charge detected

Next action events

Refund events

Customer events

​Which events to handle

​All events

​Ugwo events

​Activity events

​Double charge detected

​Next action events

​Refund events

​Customer events

Which events to handle

All events

Ugwo events

Activity events

Double charge detected

Next action events

Refund events

Customer events