What are webhooks

Webhooks allow your application to receive information about requests, clients and payments events as they occur. This documentation explains how to configure webhooks, how to authenticate, and message formats.

The webhook request is a standard HTTP POST request with a single parameter : data

The data parameter contains a JSON array of webhooks events, up to a maximum of 1 000 events.

A webhook request is initiated about once per minute or every 5 seconds in fast mode (default).

Consider to authenticate that webhooks originated from Paybox Mail's servers by following "Authenticating webhook requests" further down this page.

Format of a webhook

Every Paybox Mail webhook uses the same general data format.

                
array(
    array(
        'event' => 'PaymentrequestsSingleCreate',
        'IDrequest' => 'AAAA1234567890123'
    ),
    array(
        'event' => 'PaymentrequestsSinglePaid',
        'IDrequest' => 'AAAA1234567890123'
    ),
    array(
        'event' => 'ClientUpdate',
        'IDclient' => 'AAAA1234567890123'
    ),
    ...
)
            

Types of events

• PaymentrequestsSingleCreate : A Single payment request is created. The second key name is IDrequest and contains the ID of the request.
• PaymentrequestsSingleUpdate : A Single payment request is updated. The second key name is IDrequest and contains the ID of the request.
• PaymentrequestsSingleDelete : A Single payment request is deleted. The second key name is IDrequest and contains the ID of the request.
• PaymentrequestsSinglePaid : A Single payment request is paid. The second key name is IDrequest and contains the ID of the request.
• ClientCreate : A Client is created. The second key name is IDclient and contains the ID of the client.
• ClientUpdate : A Client is updated. The second key name is IDclient and contains the ID of the client.
• ClientDelete : A Client is deleted. The second key name is IDclient and contains the ID of the client.

Failed webhook call

If the webhook url does not return a 200 HTTP response code, the POST request will be re-attempted up to 1 000 times every 10 minutes. After 1 000 attempts (approximately 7 days), the webhook account will be deactivated and webhooks events will be lost. To avoid data loss, we recommend that you accept and store data (with an HTTP 200 response) for later processing.

Authenticating webhooks requests

Paybox Mail signs a webhook request by including X-Auth-Signature, X-Method-Signature and X-Auth-Time HTTP headers, allowing you to check that it comes from our servers. You need:

• the webhook authentication key automatically generated when creating the webhook account (webhookKey)
• the webhook’s URL, exactly as you entered it in Paybox Mail (fullUrl)
• the JSON encoded content of the POST parameter 'data' (jsonData)
• the timestamp received in the POST header 'X-Auth-Time' (time)
• the signature hash method received in the POST header 'X-Method-Signature' (hashMethod) currently 'sha1'
• the signature received in the POST header 'X-Auth-Signature' (toVerify)

follow the next steps to generate the signature:

• Set var toSign, a concatenation of fullUrl, webhookKey, jsonData and time separated by +
• hash this string with hashMethod to generate the signature and compare it with toVerify

Example

Here is an example in php:

                
$headers = getallheaders();
$toVerify = $headers['X-Auth-Signature'];
$hashMethod = $headers['X-Method-Signature'];
$time = $headers['X-Auth-Time'];
$jsonData = $_POST['data'];

$toSign = $fullUrl . '+' . $webhookKey . '+' . $jsonData . '+' . $time;
$signature = hash($hashMethod, $toSign);

if ($signature === $toVerify) {
    echo ("successful authentication");
} else {
    echo ("failed authentication");
}