Вебхуки

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.