Вебхуки

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

Додайте кінцеву точку

Лише Власник і Адміністратори робочого простору можуть додавати, тестувати й видаляти кінцеві точки.

1. Відкрийте Розробники в бічній панелі.
2. На картці Вебхуки натисніть Додати точку доступу.
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 (ім'я, телефон, електронна пошта), 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=, за яким слідує шістнадцятковий дайджест.

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, щоб упорядкувати їх.

Таблиця Вебхуки показує останній HTTP-статус кожної кінцевої точки і коли його надіслано. Кінцева точка, що дає збій, залишається активною; Ringhum не вимикає її за вас.

Тестування, призупинення й видалення

• Надіслати тест одразу надсилає подію test.ping, і повідомлення показує HTTP-статус, який повернула ваша кінцева точка.
• Перемикач Активно призупиняє кінцеву точку. Події, що відбуваються, поки її вимкнено, пізніше не надсилаються.
• Видалити видаляє кінцеву точку та її секрет.

Поширені запитання

У чому різниця з застосунками Zapier, Make і n8n у розділі Інтеграції? Ці з'єднання використовують сторінку Інтеграцій і її шість типів подій. Їхнє тіло — {"event", "workspace", "sent_at", "data"}, а коли ви встановлюєте секрет, заголовок підпису — X-Ringhum-Signature: sha256=…, HMAC-SHA256 лише від тіла. Вебхуки для розробників, описані тут, охоплюють більше подій і використовують підпис v1= із часовою позначкою. Див. Вибір того, що надсилається.

Моя кінцева точка повертає 2xx, але мій код нічого не бачить. Перевірте, що подію позначено для цієї кінцевої точки, що кінцева точка активна, і що ваш файрвол дозволяє запити з інтернету.

Чому перевірка підпису дає збій? Найчастіше тіло розбирали й перекодовували перед хешуванням. Хешуйте необроблені байти точно так, як отримано.