Webhooks

Introduction

When interacting with APIs, the expectation is typically that an endpoint will respond almost instantly. However, some queries may take longer to process, which could result in a timeout error. To avoid this, we return a pending response. To keep you informed of your request’s status, we provide webhooks that your application can listen to.

To set this up, you are required to provide a webhook URL where we can send updates. The URL should meet the following requirements:

Must be a POST endpoint
Should process JSON requests
Should return a 200 OK status immediately, allowing your application to process the data in the background

Types of events

Affinity sends webhooks for various events. Below is a detailed description of the various events we currently push.

	Event	Description
1.	`transaction.success`	A transaction has been processed successfully
2.	`transaction.failed`	A transaction has failed. Transactions cannot be retried
3.	`transaction.reversed`	A processed transaction has been reversed

Transaction webhook sample

{
  "event": "transaction.success",
  "date": "2023-02-27T13:25:16.5677375",
  "idempotencyKey": "5619fb96-4062-4d10-aa67-b169fb430873",
  "data": {
    "reference": "string",
    "status": "PROCESSING",
    "statusCode": "03",
    "createdAt": "2023-04-16 13:29:05.260646",
    "updatedAt": "2023-04-16 13:30:05.260646",
    "currency": "GHS",
    "amount": "30.00",
    "fee": "0.00",
    "note": "Deposit",
    "serviceType": "DEPOSIT"
  }
}

	Event	Description
1.	`account.updated`	An account information has been updated successfully
2.	`account.withdrawal`	An amount has been withdrawn from an account
3.	`account.deposit`	An amount has been deposited into an account
4.	`account.activated`	An account has been activated
5.	`account.approved`	An account has been approved
6.	`account.closed`	An account has been closed and will not be eligible for transactions

Account update sample

{
  "event": "account.update",
  "date": "2023-02-27T13:25:16.5677375",
  "idempotencyKey": "5619fb96-4062-4d10-aa67-b169fb430873",
  "data": {
    "reference": "8a8587d6831bbc8a01831ca042830a52",
    "name": "DAILY",
    "balances": {
      "totalBalance": 594887.18,
      "availableBalance": 594887.18,
      "type": "BUSINESS",
      "accountNumber": "2001678627650",
      "createdAt": "2022-09-08T10:37:24Z",
      "updatedAt": "2023-02-27T09:02:02Z",
      "status": "ACTIVE"
    }
  }
}

Webhooks related to the onboarding process

	Event	Description
1.	`onboard.passed`	Successful verification of an individual MKYC account
2.	`onboard.failed`	Failed verification of an individual MKYC account
3.	`account.created`	An account has been created
4.	`account.failed`	Account failed to create
5.	`upgrade.success`	Successful upgrade from individual MKYC to EKYC
6.	`upgrade.failed`	Failed EKYC upgrade

Onboard sample

{
  "event": "onboard.failed",
  "idempotencyKey": "26e42c55-65fc-416d-a0cd-0dc5049229f6",
  "date": "2024-09-04T14:46:46.047Z",
  "data": {
    "reference": "66d84cdc9a7578feb861ef06",
    "status": "FAILED",
    "partnerReference": "afftest000123",
    "errorCode": "BAD_IMAGE",
    "accountState": "CREATION",
    "accountType": "MKYC",
    "profileType": "INDIVIDUAL"
  }
}

Account created sample

{
  "event": "account.created",
  "idempotencyKey": "d47f0ab9-a2ef-485a-ab89-07b61aa01b75",
  "date": "2024-09-04T16:00:07.490Z",
  "data": {
    "reference": "66d84cdc9a7578feb861ef06",
    "status": "ACTIVE",
    "partnerReference": "afftest000123",
    "accountState": "CREATION",
    "accountType": "MKYC",
    "profileType": "INDIVIDUAL",
    "totalBalance": 0,
    "availableBalance": 0,
    "accountNumber": "20010000000"
  }
}

Upgrade sample

{
  "event": "upgrade.success",
  "idempotencyKey": "26e42c55-65fc-416d-a0cd-0dc5049229f6",
  "date": "2024-09-04T14:46:46.047Z",
  "data": {
    "reference": "66d84cdc9a7578feb861ef06",
    "status": "ACTIVE",
    "partnerReference": "afftest000123",
    "accountState": "UPGRADE",
    "accountType": "EKYC",
    "profileType": "INDIVIDUAL"
  }
}

IP whitelisting

To safeguard your applications, it is crucial to verify the source of the webhook before processing any data. Affinity will only send webhooks from the IP addresses listed below:

34.254.168.1
52.31.149.217

These IP addresses are valid for both your production and staging environments

Last modified: 27 August 2025