Вебхуки

Вебхук отправляет HTTPS-запрос на ваш сервер в тот момент, когда что-то происходит в вашем рабочем пространстве. Используйте вебхуки вместо опроса API: когда звонок завершается, вы сразу же получаете сводку, результат, собранные данные и расшифровку. Каждая доставка подписывается секретом, который известен только вам и Ringhum, поэтому ваш сервер может отклонять всё, что пришло не от Ringhum.

Добавление конечной точки

Добавлять, тестировать и удалять конечные точки могут только Владелец и Администраторы рабочего пространства.

1. Откройте Разработчикам в боковом меню.
2. В карточке Webhooks нажмите Добавить адрес.
3. Введите URL адреса. Он должен начинаться с https://.
4. В разделе События отметьте нужные события. call.ended отмечен за вас.
5. Нажмите Добавить адрес.
6. Скопируйте секрет подписи из зелёного блока (он начинается с whsec_) и сохраните его на своём сервере. Нажмите Готово.

Важно: Секрет подписи показывается только один раз. Если вы его потеряли, удалите конечную точку и добавьте её заново, чтобы получить новый секрет.

Вы можете добавить сколько угодно конечных точек. Вебхуки охватывают каждого ассистента в рабочем пространстве. Управлять конечными точками также можно через API, с помощью POST /webhooks и ключа с областью доступа write.

События

Как выглядит доставка

Каждая доставка — это запрос POST с телом в формате JSON и следующими заголовками:

POST https://example.com/hooks/ringhum
Content-Type: application/json
User-Agent: Ringhum-Webhooks/1.0
X-Ringhum-Event: call.ended
X-Ringhum-Timestamp: 1789250000
X-Ringhum-Signature: v1=5f1a…

{
  "id": "evt_8f2k…",
  "type": "call.ended",
  "created_at": "2026-09-24T14:03:11+00:00",
  "data": {
    "call_id": 4812,
    "direction": "inbound",
    "from": "+14155550132",
    "to": "+14155550100",
    "assistant_id": 3,
    "status": "completed",
    "outcome": "message_taken",
    "sentiment": "neutral",
    "duration_seconds": 94,
    "summary": "Caller asked for a quote for a kitchen repair…",
    "extracted": { "name": "Dana Lee", "reason": "Quote" },
    "transcript": [
      { "role": "assistant", "content": "Hello, you've reached…" },
      { "role": "user", "content": "Hi, I'd like a quote…" }
    ]
  }
}

Объект data зависит от события:

• call.ended и message.taken: поля звонка, показанные выше.
• call.started и call.transferred: call_id, direction, from, to, assistant_id, status и started_at.
• appointment.*: appointment_id, title, status, starts_at, ends_at, timezone, customer (имя, телефон, email), contact_id, service, staff, call_id и notes.
• order.*: order_id, number, status, fulfillment, customer, address, items с опциями и ценами, currency, subtotal, fee, total, source, call_id и, для отмен, cancel_reason.
• reservation.*: reservation_id, number, status, room, check_in, check_out, nights, adults, children, guest, currency, nightly, total и source.
• campaign.completed: campaign_id, name и счётчики прогресса кампании.

Примечание: Когда ассистент бронирует запись во время звонка, вы можете получить appointment.booked дважды. Одно отправляется в момент бронирования, с полями записи. Другое — после того, как звонок просуммирован, с полями звонка. Проверяйте, есть ли в data поле appointment_id или call_id, и используйте поле id, чтобы не обработать одну доставку дважды.

Проверка подписи

Подпись — это HMAC-SHA256 от метки времени, точки и необработанного тела запроса, с ключом — секретом подписи вашей конечной точки. Она отправляется как v1=, за которым следует hex-дайджест.

1. Прочитайте сырое тело точно так, как оно получено, до какого-либо разбора JSON.
2. Постройте строку {X-Ringhum-Timestamp}.{raw body}.
3. Вычислите HMAC-SHA256 со своим секретом и добавьте префикс v1=.
4. Сравните её с X-Ringhum-Signature, используя сравнение за постоянное время.
5. Отклоняйте запрос, если метка времени старше пяти минут, чтобы блокировать повторно воспроизведённые запросы.

Node.js:

const crypto = require('crypto');

function isValid(req, rawBody, secret) {
  const ts = req.header('X-Ringhum-Timestamp');
  const sig = req.header('X-Ringhum-Signature') || '';
  const expected = 'v1=' + crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

PHP:

$ts = $_SERVER['HTTP_X_RINGHUM_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_RINGHUM_SIGNATURE'] ?? '';
$expected = 'v1=' . hash_hmac('sha256', $ts . '.' . file_get_contents('php://input'), $secret);
if (! hash_equals($expected, $sig) || abs(time() - (int) $ts) > 300) {
    http_response_code(400);
    exit;
}

Ответы, тайм-ауты и повторы

• Отвечайте любым статусом 2xx, чтобы подтвердить доставку. Выполняйте медленную работу уже после ответа.
• Ringhum ждёт ответа до 10 секунд.
• Если ваша конечная точка не отвечает 2xx, доставка повторяется до 3 раз всего: сразу, затем ещё раз примерно через 10 секунд и последний раз примерно через 60 секунд. После этого она отбрасывается.
• Доставки могут приходить не по порядку. Используйте created_at и идентификаторы в data, чтобы упорядочить их.

Таблица Webhooks показывает последний HTTP-статус каждой конечной точки и время отправки. Неисправная конечная точка остаётся активной; Ringhum не отключает её за вас.

Тест, пауза и удаление

• Отправить тест сразу отправляет событие test.ping, а сообщение показывает HTTP-статус, который вернула ваша конечная точка.
• Переключатель Активен приостанавливает конечную точку. События, произошедшие, пока она выключена, позже не отправляются.
• Удалить удаляет конечную точку и её секрет.

Частые вопросы

В чём отличие от приложений Zapier, Make и n8n в разделе «Интеграции»? Те подключения используют страницу «Интеграции» и её шесть типов событий. Их тело — {"event", "workspace", "sent_at", "data"}, а при указании секрета заголовок подписи — X-Ringhum-Signature: sha256=…, HMAC-SHA256 только от тела. Вебхуки для разработчиков, описанные здесь, охватывают больше событий и используют подпись v1= с меткой времени. См. Выбор того, что отправляется.

Моя конечная точка возвращает 2xx, но мой код ничего не видит. Проверьте, что событие отмечено для этой конечной точки, что конечная точка активна, и что ваш файервол разрешает запросы из интернета.

Почему проверка подписи не проходит? Чаще всего тело было разобрано и заново закодировано перед хешированием. Хешируйте сырые байты точно так, как они получены.