Webhook — это автоматическое уведомление о событии, отправляемое системой Allpay на внешний URL.
Когда происходит успешный платёж, Allpay направляет POST-запрос на указанный адрес. Запрос содержит всю информацию о платеже, включая имя покупателя, предмет платежа и сумму.
Разработчики и интеграторы используют webhook для:
- автоматического запуска процессов (например, активации заказа или отправки письма покупателю),
- синхронизации данных между разными системами,
- исключения необходимости ручной проверки статуса платежа.
Типы событий
В настоящее время в Allpay доступен webhook только для одного события — успешный платёж.
Для подписок webhook автоматически отправляется каждый месяц после успешного регулярного списания.
Где настроить webhook
Webhook настраивается отдельно для каждой платёжной ссылки или API-интеграции:
- Платёжная ссылка — в её настройках. В этом случае webhook будет отправляться при каждом платеже по этой ссылке.
- 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-запросов:
- Проверка с помощью webhook secret key.
- Проверка IP-адреса отправителя.
Проверка с помощью Webhook secret key
Для этого используется HMAC-подпись, основанная на алгоритме SHA256.
Алгоритм генерации подписи:
- Удалите параметр <span class="u-richtext-element">sign</span> из запроса.
- Исключите параметры с пустыми значениями.
- Отсортируйте оставшиеся ключи по алфавиту.
- Из полученного списка возьмите значения параметров и объедините их в строку через символ «двоеточие» (
:). - Добавьте в конец строки через «двоеточие» ваш Webhook secret key.
- Примените к полученной строке алгоритм SHA256.
- Сравните результат с параметром <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 будет отключён, чтобы предотвратить дальнейшие попытки отправки.
