Webhooks 🪝

Thepeer sends webhooks for certain events. At the time of writing, we only send webhooks to receiving businesses when a transaction is performed with them.


You must set your webhook URL on your business dashboard in order to receive webhook notifications.

The transaction payload

This is the payload that is sent when a successful transaction has been carried out. This serves as a notification to the business that they have received money.

Sample transaction webhook payload

Check out the anatomy of a transaction object.


The attribute, type, will exist with the value transaction.

The authorization payload

This is the payload that is sent when a charge is about to be carried out with a user on a business. The business can process an authorization request with the appropriate events.

Sample authorization webhook payload

"type": "charge",
"charge": {
"reference": "authorization-reference",
"channel": "direct_charge",
"amount": 50000,
"currency": "NGN",
"charges": {
"amount_to_be_charged": 52750,
"included_fees": 2750
"fees": {
"percentage": 0.5,
"flat_fee": 2500
"user": {
"name": "Trojan Okoh",
"identifier": "trojan",
"identifier_type": "username",
"email": "trojan@thepeer.co",
"reference": "the-nothing"
"peer": {
"user": {
"name": "Trojan Okoh",
"identifier": "trojan@apple.com",
"identifier_type": "email"
"business": {
"name": "Apple",
"logo": "https://apple.com/logo.png"
"created_at": "2021-07-16T00:59:44.000000Z",
"updated_at": "2021-07-16T00:59:44.000000Z"


  • Values for channel can either be send, checkout, or direct_charge.

Webhook verification

Valid webhook requests have a header with the key X-Thepeer-Signature which is a HMAC SHA1 signature of the request body (hex encoded). The request body is signed using your secret key.


  • Sign the entire request body with HMAC SHA1 using your secret key.
  • Compare the result of this signing with the value of the X-Thepeer-Signature header.
  • If they match, then the request is indeed from Thepeer.

Here's an example in php:

$signature = hash_hmac('sha1', '{"message":"test signing"}', 'your-secret-key');
if ($signature === $_SERVER['X-Thepeer-Signature']) {
// return status 200
} else {
// return status 406

You must return status 200 if a webhook verification is successful. Else, Thepeer will retry a couple more times until it stops.