Эта статья объясняет, как настроить получение webhook-уведомлений о платежах.
Для платежей, инициированных через API , Allpay по умолчанию отправляет webhook в ответ на API-запрос. Дополнительная настройка для этого не требуется.
Настройка, описанная ниже, нужна в двух случаях: если вы хотите получать webhook-уведомления о платежах, созданных не через API, а через платежные ссылки, либо если вам необходимо указать дополнительный URL для отправки webhook-уведомлений в рамках API-интеграции.
Что такое webhook 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 /c96zv6ri852dvppncccdg6fxkjnpwojg HTTP/ 2
Host: hook.eu2.make.com
accept: * /*
content-type:application/json
content-length: 453
{
"name": "Consultation",
"items": [
{
"name": "Consultation",
"price": 150,
"qty": 2,
"vat": "1"
},
{
"name": "Clock",
"price": 50,
"qty": 1,
"vat": "1"
}
],
"amount": "350",
"status": 1,
"client_name": "Tanur Mikrogalov",
"client_email": "test@email.com",
"client_tehudat": "123456789",
"client_phone": "+972 58 569 8877",
"foreign_card": "0",
"card_mask": "455743******3431",
"card_brand": "visa",
"receipt": "",
"inst": 1,
"sign": "83f6fab69f7b237ee2db5d9993b84b5fe89ef722af6206a0ffe64480501f3784"
}
Каждый платёж, по которому отправлен 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 Ваш сервер должен вернуть HTTP-ответ с кодом <span class="u-richtext-element">200 OK</span>, чтобы подтвердить успешное получение webhook-запроса. Если возвращается любой другой статус, либо запрос не был доставлен из-за таймаута или сетевой ошибки, Allpay автоматически выполнит повторные попытки доставки.
Всего выполняется до 10 попыток доставки. Первая повторная попытка осуществляется через 1 минуту после неудачной отправки. Далее интервалы между попытками постепенно увеличиваются, при этом последняя попытка выполняется в течение 24 часов с момента исходного запроса.
Если все попытки доставки завершились неудачно, webhook считается недоставленным, и дальнейшие попытки выполняться не будут.
