Webhooks

Webhook — это автоматическое уведомление о событии, отправляемое системой Allpay на внешний URL.

Когда происходит успешный платёж, Allpay направляет POST-запрос на указанный адрес. Запрос содержит всю информацию о платеже, включая имя покупателя, предмет платежа и сумму.

Разработчики и интеграторы используют webhook для:

• автоматического запуска процессов (например, активации заказа или отправки письма покупателю),
• синхронизации данных между разными системами,
• исключения необходимости ручной проверки статуса платежа.

Типы событий

В настоящее время в Allpay доступен webhook только для одного события — успешный платёж.

Для подписок webhook автоматически отправляется каждый месяц после успешного регулярного списания.

Где настроить webhook

Webhook настраивается отдельно для каждой платёжной ссылки или API-интеграции:

1. Платёжная ссылка — в её настройках. В этом случае webhook будет отправляться при каждом платеже по этой ссылке.
2. API-интеграция — в настройках конкретной интеграции в разделе <span class="u-richtext-element">Интеграции по API</span>. Это позволит получать webhook по всем платежам, прошедшим через данную интеграцию. Например, с вашим сайтом на Tilda, WordPress или другой платформой.

В Allpay нет централизованной настройки webhook для всех платежей — это сделано для гибкого управления уведомлениями по различным каналам.

Содержимое webhook-запроса

Allpay отправляет POST-запрос на указанный URL. Тело запроса — это JSON-объект с параметрами, относящимися к событию.

Примера запроса

POST /tjefkki4vvsvfyhrmudkr571bvjxw5g7 HTTP/2
Host: hook.eu2.make.com
accept: */*
content-type:application/json
content-length: 653

{
    "name": "Test payment",
    "items": "[{\"name\":\"Test payment\",\"price\":10,\"qty\":1}]",
    "amount": "10",
    "status": 1,
    "client_name": "Tanur Mikrogalov",
    "client_email": "test@allpay.co.il",
    "client_tehudat": "",
    "client_phone": "",
    "foreign_card": "0",
    "card_mask": "407517******9285",
    "card_brand": "visa",
    "receipt": "https:\/\/www.allpay.co.il\/receipt.pdf",
    "sign": "2367eefa04752fae489fc233670fce599be9083af8c9a581d4c7684ec33c0114"
}

‍

Каждый платёж, по которому отправлен webhook, получает соответствующую метку на главном экране платежей. Нажав на неё, можно просмотреть содержимое запроса.

Безопасность webhook

Можно использовать два способа проверки достоверности webhook-запросов:

1. Проверка с помощью webhook secret key.
2. Проверка IP-адреса отправителя.

Проверка с помощью Webhook secret key

Для этого используется HMAC-подпись, основанная на алгоритме SHA256.

Алгоритм генерации подписи:

1. Удалите параметр <span class="u-richtext-element">sign</span> из запроса.
2. Исключите параметры с пустыми значениями.
3. Отсортируйте оставшиеся ключи по алфавиту.
4. Из полученного списка возьмите значения параметров и объедините их в строку через символ «двоеточие» (:).
5. Добавьте в конец строки через «двоеточие» ваш Webhook secret key.
6. Примените к полученной строке алгоритм SHA256.
7. Сравните результат с параметром <span class="u-richtext-element">sign</span>, переданным в запросе.

Платформы Make и Zapier позволяют реализовать такую проверку с помощью встроенных инструментов (например, скрипта в Code by Zapier).

Пример JavaScript для Zapier

const webhookKey = "YOUR WEBHOOK SECRET KEY";

// Parse the input params from JSON string to an object
const params = JSON.parse(inputData.params || '{}');

// Store the original signature from the request
const requestSignature = params.sign || null;

// Remove the 'sign' parameter before calculating the signature
delete params.sign;

function getApiSignature(params, webhookKey) {
    // Filter out empty values and sort keys alphabetically
    const sortedKeys = Object.keys(params)
        .filter((key) => {
            const value = params[key];
            return value !== null && value !== undefined && String(value).trim() !== '';
        })
        .sort();

    // Collect the values in sorted key order, process nested arrays (like "items")
    const chunks = [];
    sortedKeys.forEach(key => {
        const value = params[key];
        if (Array.isArray(value)) {
            value.forEach(item => {
                if (typeof item === 'object' && item !== null) {
                    Object.keys(item).sort().forEach(subKey => {
                        const val = item[subKey];
                        if (val !== null && val !== undefined && String(val).trim() !== '') {
                            chunks.push(String(val).trim());
                        }
                    });
                }
            });
        } else {
            chunks.push(String(value).trim());
        }
    });

    // Build the string to hash
    const baseString = chunks.join(':') + ':' + webhookKey;

    // Generate SHA256 hash
    const crypto = require('crypto');
    const hash = crypto.createHash('sha256').update(baseString).digest('hex');

    return { baseString, verifiedSignature: hash };
}

// Generate the signature
const result = getApiSignature(params, webhookKey);

// Return the original and calculated values
output = {
    requestSignature: requestSignature,
    baseString: result.baseString,
    verifiedSignature: result.verifiedSignature
};

‍

Пример проверки подписи в Zapier

‍

Проверка по IP-адресу

Более простой, но менее надежный способ — это проверять, что запрос поступил с IP-адреса сервера Allpay. IP-адрес можно запросить, обратившись в поддержку.

‍Повторные запросы и деактивация webhook

Ваш сервис должен вернуть ответ с кодом 200, чтобы подтвердить успешное получение webhook-запроса. Если возвращается любой другой статус, система выполнит до трёх дополнительных попыток доставки. После этого запрос будет считаться неудачным и повторно отправляться не будет.

Если Allpay неоднократно сталкивается с ошибками при попытке доставки webhook-запроса, соответствующий webhook будет отключён, чтобы предотвратить дальнейшие попытки отправки.