Endpoint, URL и secret
В панели Каналы → Вебхуки можно добавить несколько endpoint-ов. Для каждого задаются имя, URL, события и отдельный secret. Лимит зависит от тарифа; secret задаётся один раз и платформа не показывает его повторно. Endpoint можно временно выключить, изменить имя, URL и набор событий или удалить — секрет при этом нельзя заменить, чтобы не ломать аудит и ротацию на стороне получателя.
Проверять подпись
Читайте сырой body. Подпись — HMAC-SHA256 от {timestamp}.{body}. Отклоняйте запросы старше 300 секунд.
import { verifyWebhookRequest } from "@sapportly/sdk/webhooks";
export async function POST(request: Request) {
const event = await verifyWebhookRequest(
process.env.SAPPORTLY_WEBHOOK_SECRET ?? process.env.SUPPORTLY_WEBHOOK_SECRET!,
request,
);
// ack сразу, работу — в очередь
return new Response(null, { status: 204 });
}Тест
Нажмите «Тест» у нужного endpoint-а в Каналы → Вебхуки, вызовитеclient.webhooks.testEndpoint(id) или используйтеPOST /v1/webhooks/{id}/test. Смотрите статус и ошибку доставки у конкретного endpoint-а.
Лимиты
На бесплатном плане доступен 1 endpoint, на PRO — 3, на PRO+ — 5. Enterprise получает индивидуальный лимит. Если лимит исчерпан, панель объясняет причину и предлагает изменить тариф или удалить неиспользуемый endpoint.
Надёжная доставка
- Проверяйте подпись по сырому body до JSON-парсинга и ограничивайте timestamp окном 300 секунд.
- Возвращайте 2xx быстро, а тяжёлую работу переносите в очередь.
- Обрабатывайте повторную доставку идемпотентно по `delivery_id` или `message_id`.
- 4xx исправляйте в конфигурации; 5xx/429 считаются временными и могут повторяться.
Форма тела и типы: Вебхуки API. Для входящих достаточно message.received, для исходящих оператора — agent.reply.