Webhooks

Un webhook trimite o cerere HTTPS către serverul dumneavoastră în momentul în care se întâmplă ceva în spațiul dumneavoastră de lucru. Folosiți webhook-uri în loc să interogați repetat API-ul: când un apel se încheie, primiți rezumatul, rezultatul, detaliile colectate și transcrierea imediat. Fiecare livrare este semnată cu un secret pe care doar dumneavoastră și Ringhum îl cunoașteți, astfel încât serverul dumneavoastră poate respinge orice nu a venit de la Ringhum.

Adăugați un punct final

Doar Proprietarul spațiului de lucru și Administratorii pot adăuga, testa și elimina puncte finale.

1. Deschideți Dezvoltatori din bara laterală.
2. În cardul Webhooks, faceți clic pe Adaugă punct final.
3. Introduceți URL-ul punctului final. Trebuie să înceapă cu https://.
4. La Evenimente, bifați evenimentele dorite. call.ended este bifat pentru dumneavoastră.
5. Faceți clic pe Adaugă punct final.
6. Copiați secretul de semnare din caseta verde (începe cu whsec_) și stocați-l pe serverul dumneavoastră. Faceți clic pe Gata.

Important: Secretul de semnare este afișat o singură dată. Dacă îl pierdeți, eliminați punctul final și adăugați-l din nou pentru a obține un secret nou.

Puteți adăuga câte puncte finale aveți nevoie. Webhook-urile acoperă fiecare asistent din spațiul de lucru. Puteți gestiona puncte finale și prin API, cu POST /webhooks și o cheie care are domeniul write.

Evenimente

Cum arată o livrare

Fiecare livrare este un POST cu un corp JSON și aceste anteturi:

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

Obiectul data depinde de eveniment:

• call.ended și message.taken: câmpurile de apel de mai sus.
• call.started și call.transferred: call_id, direction, from, to, assistant_id, status și started_at.
• appointment.*: appointment_id, title, status, starts_at, ends_at, timezone, customer (nume, telefon, e-mail), contact_id, service, staff, call_id și notes.
• order.*: order_id, number, status, fulfillment, customer, address, items cu opțiuni și prețuri, currency, subtotal, fee, total, source, call_id și, pentru anulări, cancel_reason.
• reservation.*: reservation_id, number, status, room, check_in, check_out, nights, adults, children, guest, currency, nightly, total și source.
• campaign.completed: campaign_id, name și contoarele de progres ale campaniei.

Notă: Când asistentul realizează o programare în timpul unui apel, puteți primi appointment.booked de două ori. Unul este trimis pe măsură ce programarea este realizată, cu câmpurile programării. Celălalt este trimis după ce apelul este rezumat, cu câmpurile apelului. Verificați dacă data are appointment_id sau call_id și folosiți câmpul id pentru a evita procesarea aceleiași livrări de două ori.

Verificați semnătura

Semnătura este un HMAC-SHA256 al marcajului temporal, un punct și corpul brut al cererii, cu cheia setată la secretul de semnare al punctului dumneavoastră final. Este trimisă ca v1= urmat de rezumatul hex.

1. Citiți corpul brut exact cum a fost primit, înainte de orice analiză JSON.
2. Construiți șirul {X-Ringhum-Timestamp}.{corp brut}.
3. Calculați HMAC-SHA256 cu secretul dumneavoastră și prefixați-l cu v1=.
4. Comparați-l cu X-Ringhum-Signature folosind o comparație cu timp constant.
5. Respingeți cererea dacă marcajul temporal este mai vechi de cinci minute, pentru a bloca cererile retrimise.

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

Răspunsuri, expirări și reîncercări

• Răspundeți cu orice stare 2xx pentru a confirma livrarea. Faceți lucrul mai lent după ce răspundeți.
• Ringhum așteaptă până la 10 secunde pentru răspunsul dumneavoastră.
• Dacă punctul dumneavoastră final nu răspunde cu un 2xx, livrarea este încercată de până la 3 ori în total: imediat, din nou după aproximativ 10 secunde, și o ultimă dată aproximativ 60 de secunde mai târziu. După aceea este renunțată.
• Livrările pot ajunge în afara ordinii. Folosiți created_at și id-urile din data pentru a le pune în ordine.

Tabelul Webhooks arată ultima stare HTTP a fiecărui punct final și când a fost trimisă. Un punct final eșuat rămâne activ; Ringhum nu îl dezactivează pentru dumneavoastră.

Testați, întrerupeți și eliminați

• Trimite test trimite un eveniment test.ping imediat, iar un mesaj arată starea HTTP returnată de punctul dumneavoastră final.
• Comutatorul Activ întrerupe un punct final. Evenimentele care au loc cât timp este dezactivat nu sunt trimise ulterior.
• Elimină șterge punctul final și secretul său.

Întrebări frecvente

Care este diferența față de aplicațiile Zapier, Make și n8n de la Integrări? Acele conexiuni folosesc pagina Integrări și cele șase tipuri de evenimente ale sale. Corpul lor este {"event", "workspace", "sent_at", "data"}, iar când setați un secret, antetul de semnătură este X-Ringhum-Signature: sha256=…, un HMAC-SHA256 al corpului singur. Webhook-urile pentru dezvoltatori, descrise aici, acoperă mai multe evenimente și folosesc semnătura v1= cu un marcaj temporal. Consultați Alegerea a ceea ce este trimis.

Punctul meu final returnează 2xx, dar codul meu nu vede nimic. Verificați dacă evenimentul este bifat pentru acel punct final, dacă punctul final este activ, și dacă firewall-ul dumneavoastră permite cereri din internet.

De ce eșuează verificarea semnăturii? Cel mai adesea corpul a fost analizat și re-codificat înainte de a fi hash-uit. Faceți hash pe octeții bruți exact cum au fost primiți.