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 /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-запросов:

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

Ваш сервер должен вернуть HTTP-ответ с кодом <span class="u-richtext-element">200 OK</span>, чтобы подтвердить успешное получение webhook-запроса. Если возвращается любой другой статус, либо запрос не был доставлен из-за таймаута или сетевой ошибки, Allpay автоматически выполнит повторные попытки доставки.

Всего выполняется до 10 попыток доставки. Первая повторная попытка осуществляется через 1 минуту после неудачной отправки. Далее интервалы между попытками постепенно увеличиваются, при этом последняя попытка выполняется в течение 24 часов с момента исходного запроса.

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