Вебхуки

Вебхук избавляет от опроса API по таймеру. Когда в магазине создают заказ или меняют его статус, Рефсейлс отправляет POST на ваш адрес в течение нескольких секунд.

ПодключениеCopy Anchor Link

1. Откройте Настройки → Интеграции → API, раздел «Вебхуки».
2. Добавьте адрес с https:// и выберите события.
3. Сохраните секрет подписи. Он показывается один раз.
4. Нажмите «Отправить тестовое событие» и проверьте, что сервер ответил 2xx.

Вебхуки работают на тарифе «Оптимальный», как и API.

СобытияCopy Anchor Link

ФорматCopy Anchor Link

POST /refsales/webhook HTTP/1.1
Content-Type: application/json
X-Refsales-Event: order.status_changed
X-Refsales-Delivery: 5e8a1b3c-7d2f-4a6e-9c0b-81f4d2e6a9c7
X-Refsales-Signature: t=1790505600,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{
  "id": "d1a8328d-114f-4787-8182-0d88148cafff",
  "type": "order.status_changed",
  "createdAt": "2026-09-27T18:37:50.917Z",
  "data": {
    "orderId": "3f0e6c5a-2b7d-4e21-9a0f-6d1c8b4e7a52",
    "externalId": "A-1001"
  }
}

Событие короткое: в нём только ID заказа. Актуальное состояние заберите через GET /api/v1/orders/{id}. Так вы всегда видите последнюю версию, даже если события пришли не по порядку.

id события не меняется между повторами. Храните обработанные id и пропускайте дубли.

Проверка подписиCopy Anchor Link

Подпись считается как HMAC-SHA256 от строки t.тело, где t взят из заголовка, а тело берётся как пришло, до разбора JSON. Отклоняйте запросы старше 5 минут, это защищает от повторной отправки перехваченного запроса.

<?php
$secret = getenv('REFSALES_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_REFSALES_SIGNATURE'] ?? ''), $sig);

$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, $secret);
$fresh = abs(time() - (int)($sig['t'] ?? 0)) <= 300;

if (!$fresh || !hash_equals($expected, $sig['v1'] ?? '')) {
    http_response_code(400);
    exit;
}

$event = json_decode($body, true);
// поставьте $event['data']['orderId'] в очередь и ответьте сразу
http_response_code(200);

Ответ и повторыCopy Anchor Link

Ответьте 2xx в течение 10 секунд. Тяжёлую обработку делайте после ответа, через очередь.

Любой другой ответ, таймаут или обрыв связи считается неудачей. Рефсейлс повторит отправку через 1 минуту, 5 минут, 30 минут, 2 часа, 6 часов и 12 часов. После седьмой неудачи доставка останавливается, её видно в журнале в настройках. Перенаправления 3xx не выполняются, указывайте конечный адрес.

Если эндпоинт не отвечает больше суток и накопил 50 неудач подряд, Рефсейлс его выключает. Включите его в настройках, когда сервер заработает. Пропущенное заберите через синхронизацию.

Требования к адресуCopy Anchor Link

• Только https:// с действующим сертификатом.
• Адрес должен быть доступен из интернета. Локальные и внутренние адреса отклоняются. Для разработки подойдёт туннель: ngrok, cloudflared.