Вебхуки
Подготовьте свой продукт к событиям веб-перехватчика.
Создавайте и управляйте конечными точками клиентских веб-перехватчиков для использования, выставления счетов и ключевых событий жизненного цикла API, а затем подготавливайте получателей к подписанной доставке, повторным попыткам и отредактированной наблюдаемости.
Последнее обновление: July 12, 2026. Examples использование safe placeholders и сделать не включить real секреты, API ключs, или customer полезные нагрузки.
Правило получателя
Подготовьте получателей к проверке необработанной подписи полезных данных, запишите каждый идентификатор события один раз и верните 2xx только после того, как ваше приложение сможет безопасно обработать или проигнорировать событие.
Путь установки
Пять шагов от конечной точки URL до готовности к доставке.
Step 1
Создайте конечную точку получателя
Предоставьте HTTPS URL, который принимает запросы POST и может читать необработанное тело запроса перед анализом JSON.
Step 2
Выберите события
Выберите использование, подписку, счет или API ключевые типы событий жизненного цикла, к которым ваш приемник должен быть готов.
Step 3
Сохраните секрет подписи
Скопируйте секрет конечной точки один раз и сохраните его в диспетчере секретов, чтобы получатели были готовы к доставке подписанного веб-перехватчика.
Step 4
Запланировать обработку повторных попыток
Создавайте идемпотентные получатели, чтобы повторные попытки доставки были безопасными, когда включена отправка через веб-перехватчик.
Step 5
Наблюдаемость плана
Отслеживайте статус конечной точки прямо сейчас и определите записи доставки, которые понадобятся вашей команде для будущей отправки веб-перехватчика.
Конечная точка URL
Зарегистрируйте одну конечную точку для каждой среды.
Используйте отдельные URL-адреса для разработки, подготовки и производства, чтобы будущие тестовые поставки никогда не вызывали побочных эффектов в рабочей среде.
{
"name": "Production usage events",
"url": "https://example.com/api/unlimitedcodex/webhook",
"events": [
"usage.threshold_reached",
"subscription.updated",
"invoice.payment_failed"
]
}Выбор события
Выберите типы событий, к которым ваш приемник должен быть готов.
Во время подготовки доставки каждый приемник должен быть узким. Службе выставления счетов могут потребоваться только события выставления счетов, а для защиты использования могут потребоваться только фиксаторы пороговых событий.
| Событие | Контекст триггера | Вариант использования приемника |
|---|---|---|
| использование.threshold_reached | Рабочая область пересекает настроенный порог использования. | Подготовьте сообщения для владельцев аккаунтов, приостановите дорогостоящие задания или попросите владельцев счетов проверить соответствие пакета. |
| подписка.обновлено | Изменяется состояние подписки, пакет или период выставления счетов. | Обновите локальные права и сведения о доступе. |
| api_key.revoked | Ключ API отозван. | Сделайте недействительными кэшированные учетные данные и подготовьте уведомление для команды-владельца. |
| счет-фактура оплачен | Счет помечен как оплаченный. | Разблокируйте платный доступ, согласуйте состояние выставления счетов или обновите записи учетной записи. |
| счет-фактура.оплата_failed | Оплата счета не проходит. | Подготовьте поток напоминаний, сообщения владельцу учетной записи или ограничения на рискованное фоновое использование. |
Секрет подписания
Проверьте необработанное тело перед обработкой.
Секреты подписи вебхука отображаются один раз. Сохраните секрет в переменной среды или диспетчере секретов, а затем используйте его для проверки подписей с отметкой времени HMAC SHA-256, когда включена отправка веб-перехватчика.
signature value использует t=timestamp,v1=signature. Это example names header x-ucx-signature; использование signature header shown для ваш выдача.
import { createHmac, timingSafeEqual } from "crypto";
function verifySignature(rawBody, signatureHeader, secret) {
const parts = Object.fromEntries(
signatureHeader.split(",").map((part) => part.split("="))
);
const timestamp = Number(parts.t);
const signature = parts.v1;
if (!Number.isInteger(timestamp) || !signature) {
return false;
}
const signedPayload = `${timestamp}.${rawBody}`;
const expected = createHmac("sha256", secret)
.update(signedPayload)
.digest("hex");
const left = Buffer.from(expected, "hex");
const right = Buffer.from(signature, "hex");
return left.length === right.length && timingSafeEqual(left, right);
}Пример приемника
Держите обработчики небольшими и идемпотентными.
Используйте этот шаблон получателя после включения исходящей доставки: проанализируйте событие после проверки подписи, запишите идентификатор события, а затем передайте медленную работу в свою очередь.
export async function POST(request) {
const rawBody = await request.text();
const signature = request.headers.get("x-ucx-signature") ?? "";
const secret = process.env.UCX_WEBHOOK_SECRET;
if (!secret || !verifySignature(rawBody, signature, secret)) {
return new Response("Invalid signature", { status: 400 });
}
const event = JSON.parse(rawBody);
// Store event.id before doing side effects so retries stay idempotent.
await recordWebhookEvent(event.id, event.type);
return Response.json({ received: true });
}Безопасная форма полезной нагрузки
Полезную нагрузку событий следует рассматривать как операционные метаданные. Не помещайте подсказки, необработанные ключи API, данные платежных карт или секреты клиентов в настройки или журналы веб-перехватчиков.
{
"id": "evt_example_123",
"type": "usage.threshold_reached",
"created": "2026-07-06T12:00:00.000Z",
"data": {
"workspaceId": "workspace_example",
"metric": "requests",
"thresholdPercent": 80
}
}Повторные попытки
Разработан для повторных попыток доставки.
Если отправка веб-перехватчика включена, сбои сети, тайм-ауты и ответы, отличные от 2xx, могут привести к повторным попыткам. Создайте обработчики, которые могут получать одно и то же событие более одного раза без дублирования побочных эффектов.
Возврат 2хх после длительной работы
Запишите идентификатор события или поставьте работу в очередь, прежде чем вернуть успешный результат.
Используйте идентификаторы событий для идемпотентности
Игнорируйте дубликаты, которые уже были записаны или обработаны.
Держите обработчиков быстрыми
Переместите электронную почту, синхронизацию счетов и длинные задания во внутреннюю очередь.
Не зависеть от точного заказа
По возможности используйте текущее состояние ресурса вместо того, чтобы предполагать, что события происходят последовательно.
Наблюдаемость
Запланируйте отредактированный контекст конечной точки.
Планируйте записи доставки с учетом отредактированного операционного контекста, такого как тип события, конечная точка, статус, количество попыток, статус ответа, текст ответа, время следующей повторной попытки и время доставки.
Требуйте HTTPS для URL-адресов рабочих конечных точек.
Прежде чем доверять полезной нагрузке, проверьте подпись HMAC с отметкой времени.
Храните секреты подписи в диспетчере секретов, а не в исходном коде.
Считайте обработчики событий идемпотентными, поскольку попытки доставки могут повторяться.
Возвращайте 2xx только после того, как событие безопасно записано или намеренно проигнорировано.
Не регистрируйте необработанные секреты подписи, ключи API, сведения о платежах, подсказки или полезные данные клиента.
Локальное тестирование
Перед производством протестируйте туннель.
Направьте конечную точку веб-перехватчика разработки на временный туннель, подготовьте безопасное устройство событий, проверьте помощник подписи и убедитесь, что ваш обработчик хранит одну запись события.
# Use a local tunnel URL as the endpoint while testing. https://your-tunnel.example/api/unlimitedcodex/webhook # Keep the signing secret out of source code. UCX_WEBHOOK_SECRET=whsec_ucx_placeholder_value
FAQ
Вопросы по настройке вебхука.
На какие события я могу подписаться?
Управление конечными точками веб-перехватчика клиента поддерживает выбор использования.threshold_reached, subscribe.updated, api_key.revoked,voice.paid иvoice.pay_failed, поэтому получателей можно настроить до включения отправки веб-перехватчика.
Как подписываются поставки через вебхук?
Подготовьте получателей к подписи HMAC SHA-256 с отметкой времени. Значение подписи соответствует формату t=timestamp,v1=signature, и получатели должны сверить его с необработанным телом запроса и секретом подписи.
Какие предположения о доставке должен сделать мой куратор?
Если отправка через веб-перехватчик включена, не предполагайте единственную доставку, строгий порядок или успешную финальную попытку. Создавайте идемпотентные обработчики и записывайте идентификаторы событий до появления побочных эффектов.
Могу ли я изменить секрет подписи веб-перехватчика?
Да. Вращение конечной точки создает новый секрет подписи, который отображается один раз. Надежно сохраните новое значение и обновите приемник, прежде чем использовать его в производстве.
Бесплатные инструменты
Создание стартеров приемника веб-перехватчика
Обработчики шаблонов, файлы env, ключи области действия и шаблоны с безопасностью повторных попыток перед включением событий выставления счетов или использования.
Генератор вебхуков
Создайте обработчики веб-перехватчиков Node или Python с проверкой подписи для событий unlimitedcodex.
Настройка конверта
Создавайте блоки.env.example на основе выбранных конечных точек, среды и потребностей веб-перехватчика.
Конфигуратор области
Выберите рабочие нагрузки и выведите области с наименьшими привилегиями,.env.example и контрольный список ротации.
Повторить симулятор
Настройте параметры отсрочки и повтора, чтобы увидеть смоделированные результаты, и скопируйте фрагмент обработчика повтора.
Готовы подготовить приемники событий?
Соедините веб-перехватчики с элементами управления использованием и выставлением счетов.
Проверьте соответствие пакета, поведение при ограничении скорости и обработку ошибок, прежде чем рабочие процессы обработки событий клиента повлияют на системы, работающие с клиентами.