KYC and auth webhooks

By default you receive only order status changes. Two more event types are opt-in, on the Webhooks → Settings page of the merchant dashboard:

• auth — an auth event on each login or registration: when it starts, and whether it succeeded.

• kyc — a kyc event whenever a user's KYC submission changes status.

Both arrive at the same URL and are signed the same way, so branch on event in your handler. See Webhooks for the signature scheme and the retry policy.

The kyc event is the alternative to polling Get user KYC state while a submission is verifying. Verification is asynchronous and can take a while — subscribing is cheaper than a poll loop.

Auth events:

type AuthWebhook = {
  "event": "auth",
  "data": {
    "authOperation": "login" | "register",
    "authStatus": "initiate" | "success" | "failed",
    "userEmail": string,
    "date": string,
    "userCountryIsoCode": string,
    "userId"?: string
  }
}

userId is absent on an initiate for an email we have never seen — there is no user yet.

KYC events:

type KycWebhook = {
  "event": "kyc",
  "data": {
    "kycId": string,
    "kycStatus": "initiated" | "approved" | "rejected" | "invalid",
    "kycType": "basic" | "advanced",
    "userId": string,
    "userEmail": string,
    "userCountryIsoCode": string,
    "kycDocument": string,
    "date": string
  }
}

kycStatus carries the full KycStatus set, invalid included — our support team sets that when voiding a submission, and it fires this webhook like any other change. kycDocument is the document's value — BVN, NIN_V2, PASSPORT and so on — as returned in kycDocuments.

approved on a kyc event does not by itself mean the user can now order. It means that submission passed. Re-read Get user KYC state and check whether passedKycType has reached the tier the order needs.