Webhooks

Bir webhook, çalışma alanınızda bir şey olduğu anda sunucunuza bir HTTPS isteği gönderir. API'yi yoklamak (polling) yerine webhook kullanın: bir arama bittiğinde, özeti, sonucu, toplanan ayrıntıları ve dökümü hemen alırsınız. Her teslimat, yalnızca sizin ve Ringhum'un bildiği bir gizli anahtarla imzalanır, böylece sunucunuz Ringhum'dan gelmeyen her şeyi reddedebilir.

Bir uç nokta ekleme

Uç noktaları yalnızca çalışma alanı Sahibi ve Adminleri ekleyebilir, test edebilir ve kaldırabilir.

1. Kenar çubuğunda Geliştiriciler'i açın.
2. Webhooks kartında Uç nokta ekle'ye tıklayın.
3. Uç nokta URL'sini girin. https:// ile başlamalıdır.
4. Etkinlikler altında, istediğiniz olayları işaretleyin. call.ended sizin için işaretlidir.
5. Uç nokta ekle'ye tıklayın.
6. Yeşil kutudan imzalama gizli anahtarını (whsec_ ile başlar) kopyalayın ve sunucunuzda saklayın. Bitti'ye tıklayın.

Önemli: İmzalama gizli anahtarı yalnızca bir kez gösterilir. Kaybederseniz, uç noktayı kaldırın ve yeni bir gizli anahtar almak için tekrar ekleyin.

İhtiyacınız kadar uç nokta ekleyebilirsiniz. Webhook'lar, çalışma alanındaki her asistanı kapsar. Uç noktaları write kapsamına sahip bir anahtarla, POST /webhooks üzerinden API aracılığıyla da yönetebilirsiniz.

Olaylar

Bir teslimat neye benzer

Her teslimat, bir JSON gövdesi ve şu başlıklarla bir POST'tur:

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 nesnesi olaya bağlıdır:

• call.ended ve message.taken: yukarıdaki arama alanları.
• call.started ve call.transferred: call_id, direction, from, to, assistant_id, status ve started_at.
• appointment.*: appointment_id, title, status, starts_at, ends_at, timezone, customer (ad, telefon, e-posta), contact_id, service, staff, call_id ve notes.
• order.*: order_id, number, status, fulfillment, customer, address, seçenekler ve fiyatlarla items, currency, subtotal, fee, total, source, call_id ve, iptaller için, cancel_reason.
• reservation.*: reservation_id, number, status, room, check_in, check_out, nights, adults, children, guest, currency, nightly, total ve source.
• campaign.completed: campaign_id, name ve kampanyanın ilerleme sayıları.

Not: Asistan bir arama sırasında bir randevu aldığında, appointment.booked'ı iki kez alabilirsiniz. Biri, randevu alanlarıyla birlikte rezervasyon yapıldığında gönderilir. Diğeri, arama özetlendikten sonra, arama alanlarıyla birlikte gönderilir. data'nın appointment_id mi yoksa call_id mi olduğunu kontrol edin ve bir teslimatı iki kez işlemekten kaçınmak için id alanını kullanın.

İmzayı doğrulama

İmza, zaman damgasının, bir noktanın ve ham istek gövdesinin, uç noktanızın imzalama gizli anahtarıyla anahtarlanmış bir HMAC-SHA256'sıdır. v1= ardından onaltılık özet olarak gönderilir.

1. Ham gövdeyi, herhangi bir JSON ayrıştırmasından önce, alındığı gibi tam olarak okuyun.
2. {X-Ringhum-Timestamp}.{ham gövde} dizesini oluşturun.
3. Gizli anahtarınızla HMAC-SHA256'yı hesaplayın ve önüne v1= ekleyin.
4. Sabit zamanlı bir karşılaştırma kullanarak X-Ringhum-Signature ile karşılaştırın.
5. Tekrarlanan istekleri engellemek için, zaman damgası beş dakikadan eskiyse isteği reddedin.

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

Yanıtlar, zaman aşımları ve tekrar denemeler

• Teslimatı onaylamak için herhangi bir 2xx durumuyla yanıt verin. Yanıt verdikten sonra yavaş işler yapın.
• Ringhum, yanıtınız için en fazla 10 saniye bekler.
• Uç noktanız bir 2xx ile yanıt vermezse, teslimat toplamda en fazla 3 kez denenir: hemen, yaklaşık 10 saniye sonra tekrar ve yaklaşık 60 saniye sonra son bir kez. Bundan sonra bırakılır.
• Teslimatlar sırasız gelebilir. Onları sıraya koymak için created_at'i ve data içindeki kimlikleri kullanın.

Webhooks tablosu, her uç noktanın son HTTP durumunu ve ne zaman gönderildiğini gösterir. Başarısız bir uç nokta aktif kalır; Ringhum onu sizin için kapatmaz.

Test etme, duraklatma ve kaldırma

• Test gönder, hemen bir test.ping olayı gönderir ve bir mesaj, uç noktanızın döndürdüğü HTTP durumunu gösterir.
• Aktif anahtarı bir uç noktayı duraklatır. Kapalıyken olan olaylar daha sonra gönderilmez.
• Kaldır, uç noktayı ve gizli anahtarını siler.

Sık sorulan sorular

Entegrasyonlar altındaki Zapier, Make ve n8n uygulamalarından farkı nedir? Bu bağlantılar Entegrasyonlar sayfasını ve onun altı olay türünü kullanır. Gövdeleri {"event", "workspace", "sent_at", "data"}'dır ve bir gizli anahtar ayarladığınızda imza başlığı, yalnızca gövdenin bir HMAC-SHA256'sı olan X-Ringhum-Signature: sha256=…'dır. Burada anlatılan geliştirici webhook'ları daha fazla olayı kapsar ve bir zaman damgasıyla v1= imzasını kullanır. Bkz. Nelerin gönderileceğini seçme.

Uç noktam 2xx döndürüyor ama kodum hiçbir şey görmüyor. O uç nokta için olayın işaretli olduğunu, uç noktanın aktif olduğunu ve güvenlik duvarınızın internetten gelen istekleri kabul ettiğini kontrol edin.

İmza kontrolü neden başarısız oluyor? Çoğunlukla gövde, hashlenmeden önce ayrıştırılıp yeniden kodlanmıştır. Ham baytları, alındığı gibi tam olarak hashleyin.