Webhookok

Egy webhook egy HTTPS-kérést küld a szerverének abban a pillanatban, amikor valami történik a munkaterületén. Használjon webhookokat az API lekérdezgetése helyett: amikor egy hívás véget ér, azonnal megkapja az összefoglalót, az eredményt, a gyűjtött adatokat és az átiratot. Minden kézbesítés alá van írva egy titkos kulccsal, amelyet csak Ön és a Ringhum ismer, így szervere elutasíthat mindent, ami nem a Ringhumtól érkezett.

Végpont hozzáadása

Csak a munkaterület Tulajdonosa és az Adminok adhatnak hozzá, tesztelhetnek és távolíthatnak el végpontokat.

1. Nyissa meg a Fejlesztők menüpontot az oldalsávon.
2. A Webhookok kártyán kattintson a Végpont hozzáadása gombra.
3. Adja meg a Végpont URL-je mezőt. https://-sel kell kezdődnie.
4. Az Események alatt jelölje be a kívánt eseményeket. A call.ended be van jelölve Ön helyett.
5. Kattintson a Végpont hozzáadása gombra.
6. Másolja ki az aláírási titkot a zöld dobozból (whsec_-vel kezdődik), és tárolja szerverén. Kattintson a Kész gombra.

Fontos: Az aláírási titok csak egyszer jelenik meg. Ha elveszíti, távolítsa el a végpontot, és adja hozzá újra egy új titok megszerzéséhez.

Annyi végpontot adhat hozzá, amennyire szüksége van. A webhookok a munkaterület minden asszisztensére kiterjednek. A végpontokat az API-n keresztül is kezelheti, a POST /webhooks és egy write jogkörű kulcs használatával.

Események

Hogyan néz ki egy kézbesítés

Minden kézbesítés egy POST egy JSON-törzzsel és ezekkel a fejlécekkel:

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

A data objektum az eseménytől függ:

• call.ended és message.taken: a fenti hívásmezők.
• call.started és call.transferred: call_id, direction, from, to, assistant_id, status és started_at.
• appointment.*: appointment_id, title, status, starts_at, ends_at, timezone, customer (name, phone, email), contact_id, service, staff, call_id és notes.
• order.*: order_id, number, status, fulfillment, customer, address, items az opciókkal és árakkal, currency, subtotal, fee, total, source, call_id, és lemondásoknál cancel_reason.
• reservation.*: reservation_id, number, status, room, check_in, check_out, nights, adults, children, guest, currency, nightly, total és source.
• campaign.completed: campaign_id, name és a kampány előrehaladási számai.

Megjegyzés: Amikor az asszisztens egy hívás során időpontot foglal, kétszer is megkaphatja az appointment.booked eseményt. Az egyik a foglalás létrejöttekor kerül elküldésre, az időpontmezőkkel. A másik a hívás összefoglalása után, a hívásmezőkkel. Ellenőrizze, hogy a data appointment_id-t vagy call_id-t tartalmaz-e, és használja az id mezőt, hogy elkerülje egy kézbesítés kétszeri feldolgozását.

Az aláírás ellenőrzése

Az aláírás az időbélyeg, egy pont és a nyers kéréstörzs HMAC-SHA256 hasítéka, a végpontja aláírási titkával kulcsolva. v1= prefixszel kerül elküldésre, majd a hexa digest.

1. Olvassa el a nyers törzset pontosan úgy, ahogy érkezett, minden JSON-elemzés előtt.
2. Építse fel a {X-Ringhum-Timestamp}.{nyers törzs} sztringet.
3. Számítsa ki a HMAC-SHA256-ot titkos kulcsával, és fűzze elé a v1= prefixet.
4. Hasonlítsa össze az X-Ringhum-Signature értékkel, állandó idejű összehasonlítással.
5. Utasítsa el a kérést, ha az időbélyeg több mint öt perccel régebbi, hogy blokkolja az ismételt kéréseket.

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

Válaszok, időtúllépések és újrapróbálkozások

• Válaszoljon bármely 2xx státusszal a kézbesítés megerősítéséhez. A lassú munkát a válasz után végezze.
• A Ringhum legfeljebb 10 másodpercet vár a válaszára.
• Ha a végpontja nem válaszol 2xx-szel, a kézbesítést összesen legfeljebb 3-szor próbáljuk meg: azonnal, majd kb. 10 másodperc múlva újra, és egy utolsó alkalommal kb. 60 másodperccel később. Ezután eldobjuk.
• A kézbesítések nem feltétlenül sorrendben érkeznek. Használja a created_at mezőt és a data-ban lévő azonosítókat a sorba rendezéshez.

A Webhookok táblázat mutatja minden végpont legutóbbi HTTP-állapotát és mikor küldtük el. Egy sikertelen végpont aktív marad; a Ringhum nem kapcsolja ki Ön helyett.

Tesztelés, szüneteltetés és eltávolítás

• A Teszt küldése azonnal elküld egy test.ping eseményt, és egy üzenet mutatja a végpontja által visszaadott HTTP-állapotot.
• Az Aktív kapcsoló szünetelteti egy végpontot. A szünet alatt történő események nem kerülnek később elküldésre.
• Az Eltávolítás törli a végpontot és titkos kulcsát.

Gyakori kérdések

Mi a különbség a Zapier, Make és n8n alkalmazásoktól az Integrációk alatt? Azok a kapcsolatok az Integrációk oldalt és annak hat eseménytípusát használják. A törzsük {"event", "workspace", "sent_at", "data"}, és amikor titkos kulcsot állít be, az aláírásfejléc X-Ringhum-Signature: sha256=…, ami magának a törzsnek a HMAC-SHA256 hasítéka. Az itt leírt fejlesztői webhookok több eseményt fednek le, és a v1= aláírást használják egy időbélyeggel. Lásd: Az elküldött adatok kiválasztása.

A végpontom 2xx-et ad vissza, de a kódom nem lát semmit. Ellenőrizze, hogy az esemény be van-e jelölve annál a végpontnál, hogy a végpont aktív-e, és hogy a tűzfala engedélyezi-e az internetről érkező kéréseket.

Miért hiúsul meg az aláírás-ellenőrzés? Leggyakrabban a törzset elemezték és újrakódolták a hasítás előtt. Hasítsa a nyers bájtokat pontosan úgy, ahogy érkeztek.