Вебхуки

Usher може повідомляти ваші сервери про те, що відбувається в середовищі, щойно це стається: хтось приєднується, входить, змінює свої дані чи йде. Кожна подія — це підписаний POST-запит на вибрану вами адресу, який надсилається повторно, якщо ваш сервер не відповідає.

Додайте кінцеву точку

В Usher Console відкрийте середовище, а тоді Вебхуки → Нова кінцева точка. Вкажіть свою адресу https:// і виберіть події, про які вона має дізнаватися. Console один раз покаже секрет підпису кінцевої точки (whsec_…): зберігайте його разом з іншими секретами вашого сервера.

Надіслати тест надсилає подію webhook.test лише на цю кінцеву точку, хоч би на які події вона підписана.

Що надходить

POST /usher/webhooks HTTP/1.1
content-type: application/json
user-agent: Usher-Webhooks/1
webhook-id: msg_2fk7x…
webhook-timestamp: 1793643116
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

{
  "type": "user.created",
  "timestamp": "2026-11-02T18:11:56.412Z",
  "data": {
    "user": {
      "id": "Qz3m…",
      "email": "lena@acme.com",
      "emailVerified": false,
      "name": "Lena Live",
      "image": null,
      "banned": false,
      "createdAt": "2026-11-02T18:11:56.380Z",
      "updatedAt": "2026-11-02T18:11:56.380Z"
    }
  }
}

Події описують людей і сеанси, а ніколи не секрети: жодних токенів, хешів паролів, ролей і причин, з яких когось заблоковано.

Перевіряйте кожну доставку

Usher підписує події за специфікацією Standard Webhooks, тож будь-яка з її бібліотек перевірить підпис за вас. Відхиляйте все, що не проходить перевірку. Бібліотеки також відхиляють позначку часу, яка відрізняється більш ніж на п’ять хвилин, тож стару доставку не вдасться відтворити повторно.

// a route that receives Usher's webhooks (Node, the standardwebhooks package)
import { Webhook } from 'standardwebhooks'

const wh = new Webhook(process.env.USHER_WEBHOOK_SECRET!) // whsec_…, from Usher Console

export async function POST(request: Request) {
  const body = await request.text() // the raw body: the signature covers it byte for byte
  let event: { type: string; timestamp: string; data: Record<string, unknown> }
  try {
    event = wh.verify(body, Object.fromEntries(request.headers)) as typeof event
  } catch {
    return new Response('bad signature', { status: 400 })
  }
  // webhook-id is the same on every attempt: skip one you have handled already
  if (await alreadyHandled(request.headers.get('webhook-id')!)) return new Response(null, { status: 204 })
  await queue(event) // answer quickly; do the work afterwards
  return new Response(null, { status: 204 })
}

• Відповідайте протягом 15 секунд будь-яким кодом 2xx. Усе інше, зокрема переспрямування, вважається невдачею.
• Очікуйте повторів. Повідомлення зберігає свій webhook-id під час кожної спроби; пропускайте ті, які ви вже обробили.
• Не покладайтеся на порядок. Повторні спроби можуть надійти після новіших подій.

Коли ваш сервер не відповідає

Usher пробує знову через 5 секунд, 5 хвилин, 30 хвилин, 2 години, 5 годин, 10 годин і ще 10 годин (загалом близько півтори доби), а потім припиняє. Журнал доставок у Console показує спроби кожного повідомлення й останню відповідь вашого сервера, а Надіслати ще раз починає доставку заново.

Новий секрет

Новий секрет у Console створює ще один секрет і показує його один раз. Протягом наступних 24 годин кожна доставка містить два підписи, по одному для кожного секрету, тож ви можете розгорнути новий секрет, нічого не пропустивши. Після цього підписує лише новий.

Звідки надходять доставки

Вебхуки виходять з Usher через його вихідний проксі, який не підключається до приватних чи внутрішніх адрес. Кінцева точка має бути адресою https:// з публічним іменем: не IP-адресою, не приватним іменем і не адресою на власних доменах Usher.