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.

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 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"
    }
}

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
}