Webhookit

Webhook lähettää HTTPS-pyynnön palvelimellesi sillä hetkellä, kun jotain tapahtuu työtilassasi. Käytä webhookeja rajapinnan kyselemisen sijaan: kun puhelu päättyy, saat yhteenvedon, tuloksen, kerätyt tiedot ja transkription heti. Jokainen toimitus allekirjoitetaan salaisuudella, jonka vain sinä ja Ringhum tiedätte, joten palvelimesi voi hylätä kaiken, mikä ei tullut Ringhumilta.

Lisää päätepiste

Vain työtilan Omistaja ja Ylläpitäjät voivat lisätä, testata ja poistaa päätepisteitä.

1. Avaa sivupalkista Kehittäjät.
2. Napsauta Webhookit-kortissa Lisää päätepiste.
3. Syötä Päätepisteen osoite. Sen täytyy alkaa https://.
4. Valitse Tapahtumat-kohdassa haluamasi tapahtumat. call.ended on valittu sinulle valmiiksi.
5. Napsauta Lisää päätepiste.
6. Kopioi allekirjoitussalaisuus vihreästä laatikosta (se alkaa whsec_) ja tallenna se palvelimellesi. Napsauta Valmis.

Tärkeää: Allekirjoitussalaisuus näytetään vain kerran. Jos menetät sen, poista päätepiste ja lisää se uudelleen saadaksesi uuden salaisuuden.

Voit lisätä niin monta päätepistettä kuin tarvitset. Webhookit kattavat jokaisen työtilan assistentin. Voit hallita päätepisteitä myös rajapinnan kautta, käyttäen POST /webhooks ja avainta, jolla on write-käyttöoikeus.

Tapahtumat

Miltä toimitus näyttää

Jokainen toimitus on POST-pyyntö JSON-rungon ja näiden otsikoiden kanssa:

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-objekti riippuu tapahtumasta:

• call.ended ja message.taken: yllä olevat puhelukentät.
• call.started ja call.transferred: call_id, direction, from, to, assistant_id, status ja started_at.
• appointment.*: appointment_id, title, status, starts_at, ends_at, timezone, customer (nimi, puhelin, sähköposti), contact_id, service, staff, call_id ja notes.
• order.*: order_id, number, status, fulfillment, customer, address, items valintoineen ja hintoineen, currency, subtotal, fee, total, source, call_id ja, peruutuksille, cancel_reason.
• reservation.*: reservation_id, number, status, room, check_in, check_out, nights, adults, children, guest, currency, nightly, total ja source.
• campaign.completed: campaign_id, name ja kampanjan edistymislaskurit.

Huom: Kun assistentti varaa ajanvarauksen puhelun aikana, saatat vastaanottaa appointment.booked-tapahtuman kahdesti. Toinen lähetetään, kun varaus tehdään, ajanvarauskenttien kanssa. Toinen lähetetään puhelun yhteenvedon jälkeen, puhelukenttien kanssa. Tarkista, onko data-kentässä appointment_id vai call_id, ja käytä id-kenttää välttääksesi toimituksen käsittelemisen kahdesti.

Tarkista allekirjoitus

Allekirjoitus on HMAC-SHA256 aikaleimasta, pisteestä ja raakadatana olevasta pyyntörungosta, avaimena päätepisteesi allekirjoitussalaisuus. Se lähetetään muodossa v1= ja heksadesimaalitiiviste.

1. Lue raakadata täsmälleen sellaisena kuin se saapui, ennen JSON-jäsennystä.
2. Rakenna merkkijono {X-Ringhum-Timestamp}.{raw body}.
3. Laske HMAC-SHA256 salaisuudellasi ja lisää etuliite v1=.
4. Vertaa sitä X-Ringhum-Signature-otsikkoon käyttäen vakioaikaista vertailua.
5. Hylkää pyyntö, jos aikaleima on yli viisi minuuttia vanha, estääksesi toistetut pyynnöt.

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

Vastaukset, aikakatkaisut ja uudelleenyritykset

• Vastaa millä tahansa 2xx-tilalla vahvistaaksesi toimituksen. Tee hidas työ vasta vastauksen jälkeen.
• Ringhum odottaa vastaustasi enintään 10 sekuntia.
• Jos päätepisteesi ei vastaa 2xx-tilalla, toimitusta yritetään enintään 3 kertaa yhteensä: heti, uudelleen noin 10 sekunnin kuluttua, ja viimeisen kerran noin 60 sekuntia myöhemmin. Sen jälkeen se hylätään.
• Toimitukset voivat saapua väärässä järjestyksessä. Käytä created_at-kenttää ja data-kentän tunnisteita asettaaksesi ne järjestykseen.

Webhookit-taulukko näyttää jokaisen päätepisteen viimeisimmän HTTP-tilan ja lähetysajan. Epäonnistunut päätepiste pysyy aktiivisena; Ringhum ei sammuta sitä puolestasi.

Testaa, aseta tauolle ja poista

• Lähetä testi lähettää test.ping-tapahtuman heti, ja viesti näyttää päätepisteesi palauttaman HTTP-tilan.
• Aktiivinen-kytkin asettaa päätepisteen tauolle. Tapahtumia, jotka tapahtuvat sen ollessa pois päältä, ei lähetetä jälkikäteen.
• Poista poistaa päätepisteen ja sen salaisuuden.

Yleisiä kysymyksiä

Mitä eroa tällä on Zapier-, Make- ja n8n-sovelluksiin Integraatioiden alla? Nuo yhteydet käyttävät Integraatiot-sivua ja sen kuutta tapahtumatyyppiä. Niiden runko on {"event", "workspace", "sent_at", "data"}, ja kun asetat salaisuuden, allekirjoitusotsikko on X-Ringhum-Signature: sha256=…, HMAC-SHA256 pelkästä rungosta. Tässä kuvatut kehittäjäwebhookit kattavat enemmän tapahtumia ja käyttävät v1=-allekirjoitusta aikaleiman kanssa. Katso Valitse, mitä lähetetään.

Päätepisteeni palauttaa 2xx, mutta koodini ei näe mitään. Tarkista, että tapahtuma on valittu tälle päätepisteelle, että päätepiste on aktiivinen, ja että palomuurisi sallii pyynnöt internetistä.

Miksi allekirjoituksen tarkistus epäonnistuu? Yleisimmin runko jäsennettiin ja koodattiin uudelleen ennen tiivisteen laskemista. Laske tiiviste raakatavuista täsmälleen sellaisina kuin ne vastaanotettiin.