Webhooks - Pesahub

Introduction

PesaHub notifies your application of payment and payout status changes by sending an HTTP POST request to the callback_url configured on your API token. Each request body is a JSON payload with an event field identifying what happened. Payment events:

payment.received — a payment completed successfully
payment.failed — a payment attempt failed

Payout events:

payout.completed — a payout was paid out to the beneficiary
payout.failed — a payout failed
payout.refunded — a payout was refunded by the provider
payout.reversed — a payout was reversed by the provider

Use the event field to branch your handling logic. Your endpoint should respond with a 2xx status once it has accepted the webhook — a non-2xx response or timeout is treated as a failed delivery and retried.

Because deliveries can be retried, your handler must be idempotent. A redelivered webhook carries the same payload, so don’t assume you’ll only ever see an event once.

Checksum verification

Every delivery is signed with an HMAC-SHA256 signature so you can confirm a webhook is genuinely came from PesaHub and wasn’t altered in transit.

Setting up your passphrase

Signing is enabled per API token. Set a passphrase on the token under Settings > API Access — this is the secret key used to sign every webhook delivered for that token.

If no passphrase is set, webhooks are still sent to your callback_url, but without a signature.

The signature header

Signed webhooks include a Pesahub-Signature header alongside the JSON body:

POST {callback_url} HTTP/1.1
Content-Type: application/json
Pesahub-Signature: 3f9c1a...e4b2

{"event":"payment.failed","transaction_id":"...", ...}

The algorithm

The signature is computed over the JSON payload as follows:

Canonicalize

Recursively sort object keys alphabetically at every nesting level. Sequential (list) arrays keep their original order; only associative objects are sorted.

Serialize

JSON-encode the canonicalized payload with slashes unescaped and no extra whitespace.

Hash

Compute HMAC-SHA256(json, passphrase) and take the 64-character hex digest.

function canonicalize($data) {
    if ($data === null || !is_array($data)) {
        return $data;
    }

    if (array_values($data) === $data) {
        return array_map('canonicalize', $data);
    }

    ksort($data);
    $result = [];
    foreach ($data as $key => $value) {
        $result[$key] = canonicalize($value);
    }
    return $result;
}

function generateSignature(string $passphrase, array $payload): string {
    $canonical = canonicalize($payload);
    $json = json_encode($canonical, JSON_UNESCAPED_SLASHES);

    return hash_hmac('sha256', $json, $passphrase);
}

Because canonicalization sorts keys recursively, the signature is stable regardless of field order — just decode the JSON and recompute over the resulting data.

Verifying a webhook

Read the request

Read the raw JSON body and the Pesahub-Signature header.

Decode the payload

Decode the JSON body into an associative array/object.

Recompute the signature

Recompute the signature over the payload using your passphrase as the key.

Compare signatures

Compare the recomputed value against Pesahub-Signature using a timing-safe comparison (e.g. hash_equals in PHP).

Reject on mismatch

Reject the request (401/403) if they don’t match, or if the header is missing while you have a passphrase configured.

$payload = json_decode(file_get_contents('php://input'), true);
$receivedSignature = $_SERVER['HTTP_PESAHUB_SIGNATURE'] ?? null;

if (empty($receivedSignature) || !hash_equals(generateSignature($passphrase, $payload), $receivedSignature)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Signature verified - safe to process $payload

Always verify the signature before acting on the payload (e.g. before crediting an order or updating a payout status).

Notes

If you rotate your passphrase, PesaHub immediately starts signing new deliveries with the new value — update your verification code at the same time.
Retried webhooks carry the same payload and therefore the same signature — a repeated signature does not indicate a replay attack.

​Introduction

​Checksum verification

​Setting up your passphrase

​The signature header

​The algorithm

​Verifying a webhook

​Notes

Introduction

Checksum verification

Setting up your passphrase

The signature header

The algorithm

Verifying a webhook

Notes