Getting Started

Table of contents:

• Introduction
• API Key
• Making requests
  • CURL example
  • Node.js example
• Handling webhooks
  • Headers
  • Validation
• SDKs

Introduction

Payhook API works over HTTPs protocol. Both GET and POST methods can be used for making requests. To use the API you have to obtain an API Key.

API Key

API Key is generated during registration on the Dashboard and can be found on the Developer page.

Making requests

In order to make a request to Payhook API you have to make either POST or GET request on https://api.payhook.org/v1/invoke/{method}. {method} stands for a method name to be invoked. You also must provide your API Key in the X-Payhook-Api-Key header.

CURL example

curl 'https://api.payhook.org/v1/invoke/getPayment?id=1' \
  -H 'X-Payhook-Api-Key: your_api_key' \
  -H 'Accept: application/json'

Node.js example

const INVOKE_URL = 'https://api.payhook.org/v1/invoke';

const invoke = (name, params = {}) => fetch(`${INVOKE_URL}/${name}`, {
    method: 'post',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'X-Payhook-Api-Key': 'your_api_key',
    },
    body: JSON.stringify(params),
});

invoke('getPayment', { id: 1 })
    .then((paymentResult) => console.log(paymentResult));

Handling webhooks

A webhook from Payhook is sent as a POST request with JSON data. In order to proceed a webhook you must ensure that it is not fake using a signature provided as a request header.

Headers

• X-Payhook-Webhook-ID - id of the webhook
• X-Payhook-Webhook-Timestamp - timestamp of the webhook
• X-Payhook-Webhook-Event - event of the webhook (available events)
• X-Payhook-Webhook-Signature - webhook signature

Validation

In order to validate a webhook sent from payhook you have to check if hmac sha256 of the webhook request data equals to signature sent in the header X-Payhook-Webhook-Signature.

PHP Example (Laravel):

function generateSignature(string $id, string $event, string $apiKey): string
{    
    $signatureString = "id={$id}\nevent={$event}";
    
    return hash_hmac('sha256', $signatureString, $apiKey);
}

$id = request()->header('X-Payhook-Webhook-ID');
$event = request()->header('X-Payhook-Webhook-Event');
$signature = request()->header('X-Payhook-Webhook-Signature');

$apiKey = 'your_api_key';

$localSignature = generateSignature($id, $event, $apiKey);

if (!hash_equals($localSignature, $signature)) {
    abort(403, 'Invalid webhook signature!');
}

SDKs

• PHP: https://github.com/payhook-org/sdk-php