PHP: полный мануал с примерами, функциями и ООП

Webhook: сервис сам сообщает о событии

В обычном API-клиенте вы спрашиваете: «Заказ уже оплачен?». С webhook сервис при событии отправляет запрос на ваш адрес. Ваш сайт в этом разговоре принимает запрос. Формат и подтверждение приёма задаёт отправитель.

Что уже пригодится. HTTP-запрос, разбор JSON

JSON обычно читают из php://input; это не то же самое, что $_POST. Сначала проверяют подлинность исходных байтов по договору поставщика, затем используют поля. Повторная доставка события нормальна.

<?php
declare(strict_types=1);

$body = '{"event_id":"evt-7","type":"payment.succeeded","order_id":42}';
$event = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
echo $event['event_id'], "\n";
echo $event['order_id'], "\n";

evt-7
42

Следующая ступень. Следующий шаг — проверка HMAC на исходном теле и идемпотентность: повтор того же event_id не должен повторно выдавать товар.

Внешний сервис сам обращается к вашему endpoint

При обычном API-вызове ваш код спрашивает состояние. Webhook разворачивает направление: платёжный сервис сообщает, что операция изменилась. Запрос приходит без браузерной сессии и может повториться через минуту или час. Нельзя доверять полю paid=true только потому, что оно находится в JSON. Нужна проверка отправителя по протоколу провайдера, затем проверка содержимого и допустимости изменения заказа.

Подпись часто вычисляется HMAC над точными байтами тела, иногда вместе с меткой времени и другими полями. Алгоритм, кодирование подписи, разделители и формат ключа задаёт документация конкретного сервиса. Hex-строка и base64 от бинарного HMAC — разные значения. Не выбирайте алгоритм произвольно из присланного заголовка и не пересобирайте JSON до проверки: пробелы, порядок ключей и escaping изменяют байты.

HTTPS защищает канал, HMAC проверяет сообщение, временное окно ограничивает давность, а уникальный ID события предотвращает повтор обработки. Один механизм не заменяет остальные. Даже корректно подписанное событие может быть повтором или относиться к другому магазину. Сопоставляйте merchant/account, сумму, валюту и внутренний заказ по серверным данным.

Проверяем подпись до бизнес-действия

<?php
declare(strict_types=1);

function verifyEvent(string $raw, string $timestamp, string $signature, string $secret, int $now): bool {
    if (!preg_match('/\A[0-9]{10}\z/D',$timestamp)
        || !preg_match('/\A[a-f0-9]{64}\z/D',$signature)
        || abs($now-(int)$timestamp)>300) return false;
    $expected = hash_hmac('sha256',$timestamp.'.'.$raw,$secret);
    return hash_equals($expected,$signature);
}
$raw = '{"eventId":"evt-1","paid":true}';
$timestamp = '1800000000';
$secret = 'test-secret-not-for-production';
$signature = hash_hmac('sha256',$timestamp.'.'.$raw,$secret);
echo verifyEvent($raw,$timestamp,$signature,$secret,1800000001) ? "valid
" : "invalid
";
echo verifyEvent($raw.' ',$timestamp,$signature,$secret,1800000001) ? "valid
" : "invalid
";
echo verifyEvent($raw,$timestamp,$signature,$secret,1800000400) ? "valid
" : "expired
";

valid
invalid
expired

Ограничиваем вход и сохраняем исходное тело

<?php
declare(strict_types=1);

function readWebhookBody(int $maximumBytes = 262144): string {
    $stream = fopen('php://input','rb');
    if ($stream === false) throw new RuntimeException('Cannot read body');
    try {
        $body = stream_get_contents($stream,$maximumBytes+1);
        if ($body === false) throw new RuntimeException('Body read failed');
        if (strlen($body)>$maximumBytes) throw new LengthException('Payload too large');
        return $body;
    } finally {
        fclose($stream);
    }
}
// HTTP-контроллер: метод/Content-Type → readWebhookBody → подпись → json_decode.
// Здесь функция не вызывается: нет входящего HTTP-запроса.

Получите сырое тело один раз и передайте его и проверке подписи, и JSON-декодеру. Не вызывайте trim, не заменяйте переводы строк и не удаляйте пробелы. Заголовок подписи проверяют на ожидаемую структуру и допустимую длину, прежде чем выполнять сравнение. Несколько одинаковых заголовков, префиксы версий и ротация ключей требуют правил провайдера, а не догадок.

Сначала проверяется подпись и свежесть, потом JSON и схема события. Это не повод принимать неограниченное тело до HMAC: лимит ставят раньше. Ошибки клиенту сообщают кратко, а в журнал не пишут секрет и полную подпись. Для диагностики достаточно event_id после успешного разбора, безопасного кода и request_id. Ротация ключей может требовать короткого периода проверки двумя заранее доверенными ключами.

Уникальный event_id и допустимый переход состояния

После проверки вставьте event_id в таблицу входящих событий с UNIQUE. В той же транзакции проверьте и измените заказ либо сохраните задание для дальнейшей обработки. Два процесса могут одновременно проверить отсутствие события, поэтому обычная проверка SELECT без уникального ограничения не защищает от дублей. Для уже принятого события обычно возвращают успешное подтверждение, чтобы провайдер прекратил повторять его; точный статус задаётся контрактом.

Порядок доставки не гарантирован: cancelled может прийти раньше created, а старый pending — после paid. Не присваивайте статус слепо. Храните версию/время события, разрешённые переходы и при неопределённости запрашивайте актуальное состояние у провайдера. В финансовых сценариях сумма и валюта из события сверяются с заказом. Сообщение «оплачено» не должно закрыть чужой заказ с таким же внешним номером в другом аккаунте.

Быстрый ответ 2xx отправляют после надёжного сохранения принятого события, а не до него. Дорогую обработку можно вынести в очередь. Если записать не удалось, успешный ответ потеряет событие навсегда; если обработка уже произошла, а ответ потерялся, повтор должен быть безопасен. Получается тот же принцип, что у outbox, только на входной стороне: надёжно принять, затем идемпотентно обработать.

Тесты полезнее ручного «пришло один раз»

Набор проверок включает правильную подпись, подмену одного байта, старую и слишком будущую метку времени, неверную кодировку подписи, неизвестный тип события, лишние поля, неправильную сумму и повтор одного event_id. Отдельно запускают два одновременных запроса с одинаковым событием. Успешный тест должен доказать одну запись/операцию, а не просто два ответа 200.

Для отладки используйте sandbox провайдера и локально сохранённые обезличенные тела. Не повторяйте реальные платёжные уведомления на production ради проверки. Время в тестах передавайте параметром, как в примере: это позволяет проверять границу 300 секунд без ожидания. Размер хранилища принятых событий и срок дедупликации согласуют с длительностью повторов сервиса и требованиями аудита.

Подтверждение доставки и деловая семантика

Даже после успешной проверки подписи обработчик обязан убедиться, что тип события поддерживается этой версией приложения. Неизвестное событие иногда безопасно сохранить и подтвердить, а иногда требуется отказ — это определяется договором интеграции. Ответ 2xx означает принятие доставки, но не обязательно завершение всей бизнес-обработки. Храните эти состояния раздельно, чтобы поддержка могла отличить «провайдер доставил уведомление» от «заказ успешно переведён в оплаченный». Повторно запускаемый обработчик использует сохранённый event_id и не создаёт второй чек или письмо только потому, что первый ответ потерялся.

Практика: проверьте решение, а не только успешный путь

Приложение декодирует JSON, сортирует ключи, кодирует обратно и вычисляет подпись. Почему проверка падает при правильном секрете?