Webhooks 🪝

Thepeer sends webhooks for certain events, at the time of this writing; we only send webhooks to receving 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 would 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"
}
}
👀

NOTE

  • channel can be either 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.

Steps

  • 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:

<?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 unless the Thepeer will retry a couple more times until it stops.