Webhooks и подписи · Hallify Developers

Получайте события предзаказов

В настройках обслуживания заведения откройте «Интеграции», выберите ключ с webhooks:manage и зарегистрируйте публичный HTTPS-адрес и нужные типы событий. Одноразово выданный секрет храните на принимающем сервере.

События: preorder.quote_issued, preorder.quote_accepted, preorder.confirmed, preorder.changed, preorder.canceled, preorder.ready, preorder.out_for_delivery и preorder.completed. Доставка содержит x-hallify-delivery-id, x-hallify-timestamp и x-hallify-signature. Исходящие подписи предзаказов имеют вид v1=<hex>; это отдельный протокол от входящих внешних заказов. Обрабатывайте повторы идемпотентно и возвращайте успех после надёжного принятия события.

Подпись исходящего предзаказа: HMAC-SHA256 от unixSeconds + "." + стабильного JSON с рекурсивной сортировкой ключей, секрет — выданный текст в UTF-8, результат — v1=<hex>. Сервер отправляет обычный JSON: перед проверкой подписи разберите тело и примените такую же сортировку. Пример ниже выбирает допустимый возраст 300 секунд как правило получателя; это не общее правило исходящей доставки Hallify.

Конверт содержит id, type, occurredAt, data и salesChannelId. Для событий исполнения data содержит venueId, orderId, fulfillmentId, revision, status, serviceMode и scheduledFor. События предложений содержат quoteId, необязательный orderId, revision, status, serviceMode, scheduledFor, total и currency вместе с venueId. Устраняйте повторы по id события; заголовок x-hallify-delivery-id идентифицирует запись доставки.

Успех — HTTP 2xx в пределах тайм-аута 8 секунд. Сетевые ошибки, 408, 429 и 5xx повторяются с экспоненциальной задержкой от 30 секунд; максимум 8 попыток. Остальные 4xx, ошибки конфигурации и исчерпание попыток переводят доставку в DEAD_LETTER. Проверьте endpoint, активность подписки, ключа и канала перед разрешённым повтором из кабинета.

Примеры запросов

import { createHmac, timingSafeEqual } from 'node:crypto';

const stable = (value) => Array.isArray(value) ? value.map(stable)
  : value !== null && typeof value === 'object'
    ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]))
    : value;

export function verifyPreorderWebhook(payload, timestamp, signature, now = Date.now()) {
  const fresh = /^\d+$/.test(timestamp)
    && Math.abs(now / 1000 - Number(timestamp)) <= 300;
  const validFormat = /^v1=[0-9a-f]{64}$/.test(signature);
  if (!fresh || !validFormat) return false;
  const expected = createHmac('sha256', process.env.HALLIFY_SIGNING_SECRET)
    .update(timestamp + '.' + JSON.stringify(stable(payload)))
    .digest();
  return timingSafeEqual(Buffer.from(signature.slice(3), 'hex'), expected);
}

Выберите правильный HMAC-профиль

Внешние заказы используют RFC3339, JSON со стабильной сортировкой ключей, выданный секрет как UTF-8 и строчный hex. Workforce сортирует JSON рекурсивно и допускает префикс sha256=. Коммуникации подписывают JSON.stringify разобранного DTO и представляют подпись в base64url. Платежи используют стабильный JSON и v1=<hex>. Окно времени этих профилей — 300 секунд.

Аудит использует Unix-время в секундах и исходные байты UTF-8 NDJSON. Перед подписью декодируйте выданный base64url-секрет в 32 байта. Повторные подписи аудита отклоняются; другие профили используют идентификаторы событий, ревизии или хеши содержимого. Серверный пример конкретного профиля находится на странице метода.

Callbacks провайдеров

Callbacks Plaid и Salt Edge создаёт банковский провайдер; они используют собственные ключи проверки и подписи. Это не универсальные HMAC-методы. Настройка и сертификация провайдера отделены от наличия описанного HTTP-контракта.

Банковские callbacks