Webhooks

A webhook is a request that Collect sends to your server to alert you of an event. Adding support for webhooks allows you to receive real-time notifications from Collect when things happen in your account, so you can take automated actions in response, for example:

When a payment fails due to lack of funds, retry it automatically

When a customer bank account is disconnected, notify the customer

When a customer’s subscription generates a new payment, record that payment against their account.

Building a webhook handler

Webhooks are HTTP POST requests made to the URL you provided, with a JSON body.

The first step to take when you receive a webhook is to check its signature - this makes sure that is genuinely from Collect and hasn’t been forged. A signature is provided in the X-Collect-Signature header of the request. You just need to compute the signature on your end using the POSTed JSON and your business secret key, and compare it to the one in the header.

If they match, the webhook is genuine, because only you and Collect know the secret. It’s important that you keep the secret safe.

We can compute the signature like this:

Supported Events

{
  "event": "payment.success",
  "payment": {
    "id": 25,
    "ip": "::1",
    "fee": 1500,
    "amount": 150000,
    "status": "success",
    "channel": "direct-debit",
    "country": "NG",
    "paid_at": "2021-05-18T20:57:26.905Z",
    "currency": "NGN",
    "metadata": null,
    "initiator": "plan",
    "reference": "TX_QX661E6JEYTRLW9",
    "charged_at": "2021-05-18T20:57:26.905Z",
    "created_at": "2021-05-18T19:56:35.432Z",
    "updated_at": "2021-05-18T19:57:26.803Z",
    "description": "Payment for string"
  },
  "customer": {
    "id": 16,
    "code": "CUS_grhjxngq1v",
    "email": "wale@collect.africa",
    "country": "NG",
    "metadata": null,
    "last_name": "Test",
    "created_at": "2021-04-18T17:38:13.341Z",
    "first_name": "Customer",
    "updated_at": "2021-04-18T17:38:13.341Z",
    "middle_name": "null",
    "phone_number": null
  },
  "bank_account": {
    "id": 15,
    "country": "NG",
    "currency": "NGN",
    "bank_name": "Ecobank Nigeria",
    "is_active": true,
    "is_reusable": true,
    "signature": "SIG_cbf12b91eb70bbfe487f597ad0c70e5abe2cc427bff9180530ff27acff4e6a165bcb50720d506b5443e684add0757f88ef3b85a7c7c45e2f625d72f00df269b6",
    "created_at": "2021-05-18T19:33:27.213Z",
    "is_default": false,
    "updated_at": "2021-05-18T19:57:26.842Z",
    "account_name": "Test Customer",
    "authorization_code": "BA_m5qsj85sue7d9ux",
    "masked_account_number": "******1603"
  }
}

{
  "event": "payment.failed",
  "payment": {
    "id": 25,
    "ip": "::1",
    "fee": 1500,
    "amount": 150000,
    "status": "failed",
    "channel": "direct-debit",
    "country": "NG",
    "paid_at": "2021-05-18T20:57:26.905Z",
    "currency": "NGN",
    "metadata": null,
    "initiator": "plan",
    "reference": "TX_QX661E6JEYTRLW9",
    "charged_at": "2021-05-18T20:57:26.905Z",
    "created_at": "2021-05-18T19:56:35.432Z",
    "updated_at": "2021-05-18T19:57:26.803Z",
    "description": "Payment for string"
  },
  "customer": {
    "id": 16,
    "code": "CUS_grhjxngq1v",
    "email": "wale@collect.africa",
    "country": "NG",
    "metadata": null,
    "last_name": "Test",
    "created_at": "2021-04-18T17:38:13.341Z",
    "first_name": "Customer",
    "updated_at": "2021-04-18T17:38:13.341Z",
    "middle_name": "null",
    "phone_number": null
  },
  "bank_account": {
    "id": 15,
    "country": "NG",
    "currency": "NGN",
    "bank_name": "Ecobank Nigeria",
    "is_active": false,
    "is_reusable": false,
    "signature": "SIG_cbf12b91eb70bbfe487f597ad0c70e5abe2cc427bff9180530ff27acff4e6a165bcb50720d506b5443e684add0757f88ef3b85a7c7c45e2f625d72f00df269b6",
    "created_at": "2021-05-18T19:33:27.213Z",
    "is_default": false,
    "updated_at": "2021-05-18T19:57:26.842Z",
    "account_name": "Test Customer",
    "authorization_code": "BA_m5qsj85sue7d9ux",
    "masked_account_number": "******1603"
  }
}

{
  "event": "mandate.connected",
  "customer": {
    "id": 16,
    "code": "CUS_grhjxngq1v",
    "email": "wale@collect.africa",
    "country": "NG",
    "metadata": null,
    "last_name": "Customer",
    "created_at": "2021-04-18T17:38:13.341Z",
    "first_name": "Test",
    "updated_at": "2021-04-18T17:38:13.341Z",
    "middle_name": null,
    "phone_number": null
  },
  "bank_account": {
    "id": 15,
    "country": "NG",
    "currency": "NGN",
    "bank_name": "Ecobank Nigeria",
    "is_active": true,
    "is_reusable": false,
    "signature": "SIG_cbf12b91eb70bbfe487f597ad0c70e5abe2cc427bff9180530ff27acff4e6a165bcb50720d506b5443e684add0757f88ef3b85a7c7c45e2f625d72f00df269b6",
    "created_at": "2021-05-18T19:33:27.213Z",
    "is_default": false,
    "updated_at": "2021-05-18T19:57:26.042Z",
    "account_name": "Wale Kslkasl",
    "authorization_code": "BA_m5qsj85sue7d9ux",
    "masked_account_number": "******1603"
  }
}

{
  "event": "transfer.sucess",
  "transfer": {
    "id": 17,
    "fee": 5000,
    "amount": 22200,
    "source": "balance",
    "status": "success",
    "country": "NG",
    "currency": "NGN",
    "metadata": {},
    "narration": "string",
    "reference": "stg1118901",
    "created_at": "2021-05-23T09:01:50.273Z",
    "short_code": "TRF_2r52ppbhzo",
    "updated_at": "2021-05-24T07:22:08.795Z",
    "transferred_at": "2021-05-24T06:51:43.067Z"
  }
}

{
  "event": "transfer.failed",
  "transfer": {
    "id": 17,
    "fee": 5000,
    "amount": 22200,
    "source": "balance",
    "status": "failed",
    "country": "NG",
    "currency": "NGN",
    "metadata": {},
    "narration": "string",
    "reference": "stg1118901",
    "created_at": "2021-05-23T09:01:50.273Z",
    "short_code": "TRF_2r52ppbhzo",
    "updated_at": "2021-05-24T07:22:08.795Z",
    "transferred_at": "2021-05-24T06:51:43.067Z"
  }
}

Webhooks

Building a webhook handler#

Supported Events#

Building a webhook handler

Supported Events