Webhooks

En webhook skickar en HTTPS-förfrågan till din server i det ögonblick något händer i din arbetsyta. Använd webhooks i stället för att fråga API:et upprepade gånger: när ett samtal avslutas får du sammanfattningen, utfallet, insamlade uppgifter och transkriberingen direkt. Varje leverans signeras med en hemlighet bara du och Ringhum känner till, så din server kan avvisa allt som inte kom från Ringhum.

Lägg till en slutpunkt

Bara arbetsytans Ägare och Administratörer kan lägga till, testa och ta bort slutpunkter.

1. Öppna Utvecklare i sidomenyn.
2. I kortet Webhooks klickar du på Lägg till slutpunkt.
3. Ange Slutpunkts-URL. Den måste börja med https://.
4. Under Händelser kryssar du i händelserna du vill ha. call.ended är ikryssad åt dig.
5. Klicka på Lägg till slutpunkt.
6. Kopiera signeringshemligheten från den gröna rutan (den börjar med whsec_) och spara den på din server. Klicka på Klar.

Viktigt: Signeringshemligheten visas bara en gång. Om du tappar bort den, ta bort slutpunkten och lägg till den igen för att få en ny hemlighet.

Du kan lägga till så många slutpunkter du behöver. Webhooks täcker varje assistent i arbetsytan. Du kan också hantera slutpunkter via API:et, med POST /webhooks och en nyckel som har behörigheten write.

Händelser

Hur en leverans ser ut

Varje leverans är en POST med en JSON-body och dessa headers:

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

Objektet data beror på händelsen:

• call.ended och message.taken: samtalsfälten ovan.
• call.started och call.transferred: call_id, direction, from, to, assistant_id, status och started_at.
• appointment.*: appointment_id, title, status, starts_at, ends_at, timezone, customer (namn, telefon, e-post), contact_id, service, staff, call_id och notes.
• order.*: order_id, number, status, fulfillment, customer, address, items med tillval och priser, currency, subtotal, fee, total, source, call_id och, för avbokningar, cancel_reason.
• reservation.*: reservation_id, number, status, room, check_in, check_out, nights, adults, children, guest, currency, nightly, total och source.
• campaign.completed: campaign_id, name och kampanjens förloppsräkningar.

Obs: När assistenten bokar en tid under ett samtal kan du få appointment.booked två gånger. En skickas när bokningen görs, med tidsfälten. Den andra skickas efter att samtalet sammanfattats, med samtalsfälten. Kontrollera om data har appointment_id eller call_id och använd id-fältet för att undvika att bearbeta en leverans två gånger.

Verifiera signaturen

Signaturen är en HMAC-SHA256 av tidsstämpeln, en punkt, och den råa förfrågningskroppen, nyckelad med din slutpunkts signeringshemlighet. Den skickas som v1= följt av hex-digesten.

1. Läs den råa kroppen exakt som den mottogs, innan någon JSON-tolkning.
2. Bygg strängen {X-Ringhum-Timestamp}.{rå body}.
3. Beräkna HMAC-SHA256 med din hemlighet och lägg till prefixet v1=.
4. Jämför den med X-Ringhum-Signature med en konstant-tid-jämförelse.
5. Avvisa förfrågan om tidsstämpeln är mer än fem minuter gammal, för att blockera återspelade förfrågningar.

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, tidsgränser och nya försök

• Svara med valfri 2xx-status för att bekräfta leveransen. Gör långsamt arbete efter att du svarat.
• Ringhum väntar upp till 10 sekunder på ditt svar.
• Om din slutpunkt inte svarar med en 2xx försöks leveransen upp till 3 gånger totalt: direkt, igen efter cirka 10 sekunder, och en sista gång cirka 60 sekunder senare. Därefter kastas den.
• Leveranser kan anlända i fel ordning. Använd created_at och id:na i data för att ordna dem.

Tabellen Webhooks visar varje slutpunkts senaste HTTP-status och när den skickades. En misslyckad slutpunkt förblir aktiv; Ringhum stänger inte av den åt dig.

Testa, pausa och ta bort

• Skicka test skickar en test.ping-händelse direkt, och ett meddelande visar HTTP-statusen din slutpunkt returnerade.
• Brytaren Aktiv pausar en slutpunkt. Händelser som sker medan den är av skickas inte senare.
• Ta bort raderar slutpunkten och dess hemlighet.

Vanliga frågor

Vad är skillnaden mot Zapier-, Make- och n8n-apparna under Integrationer? De anslutningarna använder sidan Integrationer och dess sex händelsetyper. Deras body är {"event", "workspace", "sent_at", "data"}, och när du ställer in en hemlighet är signaturheadern X-Ringhum-Signature: sha256=…, en HMAC-SHA256 av bara bodyn. Utvecklarwebhooks, beskrivna här, täcker fler händelser och använder v1=-signaturen med en tidsstämpel. Se Välja vad som skickas.

Min slutpunkt returnerar 2xx men min kod ser inget. Kontrollera att händelsen är ikryssad för den slutpunkten, att slutpunkten är aktiv, och att din brandvägg tillåter förfrågningar från internet.

Varför misslyckas signaturkontrollen? Oftast tolkades och kodades bodyn om innan hashning. Hasha de råa bytena exakt som de mottogs.