Webhooker

En webhook sender en HTTPS-forespørsel til serveren din i det øyeblikket noe skjer i arbeidsområdet ditt. Bruk webhooker i stedet for å polle API-et: når en samtale avsluttes, mottar du sammendraget, resultatet, de innsamlede detaljene og transkripsjonen med en gang. Hver levering signeres med en hemmelighet bare du og Ringhum kjenner, slik at serveren din kan avvise alt som ikke kom fra Ringhum.

Legg til et endepunkt

Bare arbeidsområdets Eier og administratorer kan legge til, teste og fjerne endepunkter.

1. Åpne Utviklere i sidemenyen.
2. I kortet Webhooks klikker du på Legg til endepunkt.
3. Skriv inn Endepunkt-URL. Den må starte med https://.
4. Under Hendelser krysser du av for hendelsene du vil ha. call.ended er avkrysset for deg.
5. Klikk på Legg til endepunkt.
6. Kopier signeringshemmeligheten fra den grønne boksen (den starter med whsec_) og lagre den på serveren din. Klikk på Ferdig.

Viktig: Signeringshemmeligheten vises bare én gang. Hvis du mister den, fjerner du endepunktet og legger det til på nytt for å få en ny hemmelighet.

Du kan legge til så mange endepunkter du trenger. Webhooker dekker hver assistent i arbeidsområdet. Du kan også administrere endepunkter via API-et, med POST /webhooks og en nøkkel som har tilgangen write.

Hendelser

Slik ser en levering ut

Hver levering er en POST med en JSON-body og disse headerne:

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-objektet avhenger av hendelsen:

• call.ended og message.taken: samtalefeltene over.
• call.started og call.transferred: call_id, direction, from, to, assistant_id, status og started_at.
• appointment.*: appointment_id, title, status, starts_at, ends_at, timezone, customer (navn, telefon, e-post), contact_id, service, staff, call_id og notes.
• order.*: order_id, number, status, fulfillment, customer, address, items med alternativer og priser, currency, subtotal, fee, total, source, call_id og, for kanselleringer, cancel_reason.
• reservation.*: reservation_id, number, status, room, check_in, check_out, nights, adults, children, guest, currency, nightly, total og source.
• campaign.completed: campaign_id, name og kampanjens fremdriftstall.

Merk: Når assistenten bestiller en avtale under en samtale, kan du motta appointment.booked to ganger. Den ene sendes idet bestillingen gjøres, med avtalefeltene. Den andre sendes etter at samtalen er oppsummert, med samtalefeltene. Sjekk om data har appointment_id eller call_id, og bruk id-feltet for å unngå å behandle en levering to ganger.

Bekreft signaturen

Signaturen er en HMAC-SHA256 av tidsstempelet, et punktum, og den rå forespørselsbodyen, nøklet med endepunktets signeringshemmelighet. Den sendes som v1= etterfulgt av hex-sammendraget.

1. Les den rå bodyen nøyaktig slik den ble mottatt, før noen JSON-parsing.
2. Bygg strengen {X-Ringhum-Timestamp}.{raw body}.
3. Regn ut HMAC-SHA256 med hemmeligheten din og sett v1= foran.
4. Sammenlign den med X-Ringhum-Signature ved hjelp av en konstant-tid-sammenligning.
5. Avvis forespørselen hvis tidsstempelet er mer enn fem minutter gammelt, for å blokkere gjenspilte forespørsler.

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

Svar, tidsavbrudd og nye forsøk

• Svar med en hvilken som helst 2xx-status for å bekrefte leveransen. Gjør tregt arbeid etter at du har svart.
• Ringhum venter opptil 10 sekunder på svaret ditt.
• Hvis endepunktet ditt ikke svarer med en 2xx, prøves leveransen opptil 3 ganger totalt: med en gang, igjen etter omtrent 10 sekunder, og en siste gang omtrent 60 sekunder senere. Etter det forkastes den.
• Leveranser kan komme i feil rekkefølge. Bruk created_at og ID-ene i data for å sette dem i riktig rekkefølge.

Tabellen Webhooks viser hvert endepunkts siste HTTP-status og når den ble sendt. Et endepunkt som feiler, forblir aktivt; Ringhum slår det ikke av for deg.

Test, pause og fjern

• Send test sender en test.ping-hendelse med en gang, og en melding viser HTTP-statusen endepunktet ditt returnerte.
• Bryteren Aktiv pauser et endepunkt. Hendelser som skjer mens den er av, sendes ikke senere.
• Fjern sletter endepunktet og hemmeligheten dets.

Vanlige spørsmål

Hva er forskjellen fra Zapier-, Make- og n8n-appene under Integrasjoner? Disse tilkoblingene bruker Integrasjoner-siden og dens seks hendelsestyper. Bodyen deres er {"event", "workspace", "sent_at", "data"}, og når du setter en hemmelighet, er signaturheaderen X-Ringhum-Signature: sha256=…, en HMAC-SHA256 av bare bodyen. Utviklerwebhooker, beskrevet her, dekker flere hendelser og bruker v1=-signaturen med et tidsstempel. Se Velge hva som sendes.

Endepunktet mitt returnerer 2xx, men koden min ser ingenting. Sjekk at hendelsen er avkrysset for det endepunktet, at endepunktet er aktivt, og at brannmuren din tillater forespørsler fra internett.

Hvorfor feiler signatursjekken? Oftest ble bodyen parset og re-kodet før hashing. Hash de rå bytene nøyaktig slik de ble mottatt.