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, получает соответствующую метку на главном экране платежей. Нажав на неё, можно просмотреть содержимое запроса.
Параметр add_field Если в URL платёжной ссылки добавить <span class="u-richtext-element">?add_field=any-string</span>, этот параметр будет включён в тело запроса 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 VIDEO
Проверка по IP-адресу Более простой, но менее надежный способ — это проверять, что запрос поступил с IP-адреса сервера Allpay. IP-адрес можно запросить, обратившись в поддержку.
Повторные запросы и деактивация webhook Ваш сервис должен вернуть ответ с кодом 200, чтобы подтвердить успешное получение webhook-запроса. Если возвращается любой другой статус, система выполнит до трёх дополнительных попыток доставки. После этого запрос будет считаться неудачным и повторно отправляться не будет.
Если Allpay неоднократно сталкивается с ошибками при попытке доставки webhook-запроса, соответствующий webhook будет отключён, чтобы предотвратить дальнейшие попытки отправки.
