Webhooky

Webhook odešle HTTPS požadavek na váš server ve chvíli, kdy se ve vašem pracovním prostoru něco stane. Místo dotazování API použijte webhooky: když hovor skončí, dostanete ihned shrnutí, výsledek, zjištěné údaje a přepis. Každé doručení je podepsáno tajným klíčem, který znáte jen vy a Ringhum, takže váš server může odmítnout cokoli, co nepřišlo z Ringhum.

Přidání koncového bodu

Koncové body může přidávat, testovat a odebírat jen Vlastník pracovního prostoru a Správci.

1. V postranním panelu otevřete Vývojáři.
2. Na kartě Webhooky klikněte na Přidat koncový bod.
3. Zadejte URL koncového bodu. Musí začínat na https://.
4. V sekci Události zaškrtněte požadované události. call.ended je zaškrtnuto za vás.
5. Klikněte na Přidat koncový bod.
6. Zkopírujte podpisový tajný klíč ze zeleného boxu (začíná na whsec_) a uložte jej na svém serveru. Klikněte na Hotovo.

Důležité: Podpisový tajný klíč se zobrazí jen jednou. Pokud jej ztratíte, odeberte koncový bod a přidejte jej znovu, čímž získáte nový klíč.

Koncových bodů můžete přidat, kolik potřebujete. Webhooky pokrývají každého asistenta v pracovním prostoru. Koncové body můžete spravovat i přes API pomocí POST /webhooks a klíče s oprávněním write.

Události

Jak vypadá doručení

Každé doručení je POST s tělem JSON a těmito hlavičkami:

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…" }
    ]
  }
}

Objekt data závisí na události:

• call.ended a message.taken: výše uvedená pole hovoru.
• call.started a call.transferred: call_id, direction, from, to, assistant_id, status a started_at.
• appointment.*: appointment_id, title, status, starts_at, ends_at, timezone, customer (jméno, telefon, e-mail), contact_id, service, staff, call_id a notes.
• order.*: order_id, number, status, fulfillment, customer, address, items s možnostmi a cenami, currency, subtotal, fee, total, source, call_id a u zrušení cancel_reason.
• reservation.*: reservation_id, number, status, room, check_in, check_out, nights, adults, children, guest, currency, nightly, total a source.
• campaign.completed: campaign_id, name a počty postupu kampaně.

Poznámka: Když asistent během hovoru zarezervuje termín, můžete dostat appointment.booked dvakrát. Jedno se odesílá ve chvíli rezervace, s poli termínu. Druhé se odesílá po shrnutí hovoru, s poli hovoru. Zkontrolujte, zda data obsahuje appointment_id, nebo call_id, a pomocí pole id zabraňte dvojímu zpracování jednoho doručení.

Ověření podpisu

Podpis je HMAC-SHA256 z časového razítka, tečky a syrového těla požadavku, podepsaný podpisovým tajným klíčem vašeho koncového bodu. Odesílá se jako v1= následované hexadecimálním otiskem.

1. Přečtěte syrové tělo přesně tak, jak bylo přijato, ještě před jakýmkoli parsováním JSON.
2. Sestavte řetězec {X-Ringhum-Timestamp}.{raw body}.
3. Spočítejte HMAC-SHA256 se svým tajným klíčem a přidejte předponu v1=.
4. Porovnejte jej s X-Ringhum-Signature pomocí porovnání v konstantním čase.
5. Odmítněte požadavek, pokud je časové razítko starší než pět minut, abyste zablokovali opakovaně přehrané požadavky.

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;
}

Odpovědi, časové limity a opakování

• Odpovězte jakýmkoli stavem 2xx, čímž doručení potvrdíte. Pomalejší práci proveďte až po odpovědi.
• Ringhum čeká na vaši odpověď až 10 sekund.
• Pokud váš koncový bod neodpoví 2xx, doručení se zkusí odeslat celkem až 3krát: ihned, znovu asi po 10 sekundách a naposledy asi o 60 sekund později. Poté se zahodí.
• Doručení mohou přicházet v jiném pořadí. K jejich seřazení použijte created_at a id v data.

Tabulka Webhooky zobrazuje poslední HTTP stav každého koncového bodu a čas odeslání. Nefunkční koncový bod zůstává aktivní; Ringhum jej za vás nevypíná.

Test, pozastavení a odebrání

• Odeslat test ihned odešle událost test.ping a zpráva zobrazí HTTP stav, který váš koncový bod vrátil.
• Přepínač Aktivní pozastaví koncový bod. Události, které nastanou, dokud je vypnutý, se dodatečně neodesílají.
• Odebrat smaže koncový bod i jeho tajný klíč.

Časté dotazy

Jaký je rozdíl oproti aplikacím Zapier, Make a n8n v Integracích? Tato propojení používají stránku Integrace a jejích šest typů událostí. Jejich tělo je {"event", "workspace", "sent_at", "data"} a při nastavení tajného klíče je hlavička podpisu X-Ringhum-Signature: sha256=…, HMAC-SHA256 pouze z těla. Vývojářské webhooky popsané zde pokrývají více událostí a používají podpis v1= s časovým razítkem. Viz Výběr toho, co se odesílá.

Můj koncový bod vrací 2xx, ale můj kód nic nevidí. Zkontrolujte, že je pro daný koncový bod zaškrtnutá událost, že je koncový bod aktivní a že váš firewall povoluje požadavky z internetu.

Proč selhává ověření podpisu? Nejčastěji bylo tělo před hashováním naparsováno a znovu zakódováno. Hashujte přesně syrové bajty tak, jak byly přijaty.