Уебхукове

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.