Webhooks

Ein Webhook sendet in dem Moment, in dem in Ihrem Workspace etwas geschieht, eine HTTPS-Anfrage an Ihren Server. Nutzen Sie Webhooks statt die API abzufragen: Endet ein Anruf, erhalten Sie Zusammenfassung, Ergebnis, erfasste Details und Transkript sofort. Jede Zustellung ist mit einem Geheimnis signiert, das nur Sie und Ringhum kennen, sodass Ihr Server alles ablehnen kann, was nicht von Ringhum stammt.

Einen Endpunkt hinzufügen

Nur der Workspace-Owner und Admins können Endpunkte hinzufügen, testen und entfernen.

1. Öffnen Sie Entwickler in der Seitenleiste.
2. Klicken Sie in der Karte Webhooks auf Endpunkt hinzufügen.
3. Geben Sie die Endpunkt-URL ein. Sie muss mit https:// beginnen.
4. Haken Sie unter Ereignisse die gewünschten Ereignisse an. call.ended ist bereits angehakt.
5. Klicken Sie auf Endpunkt hinzufügen.
6. Kopieren Sie das Signaturgeheimnis aus dem grünen Feld (es beginnt mit whsec_) und bewahren Sie es auf Ihrem Server auf. Klicken Sie auf Fertig.

Wichtig: Das Signaturgeheimnis wird nur einmal angezeigt. Falls Sie es verlieren, entfernen Sie den Endpunkt und fügen Sie ihn erneut hinzu, um ein neues Geheimnis zu erhalten.

Sie können so viele Endpunkte hinzufügen, wie Sie benötigen. Webhooks decken jeden Assistenten im Workspace ab. Sie können Endpunkte auch über die API verwalten, mit POST /webhooks und einem Schlüssel mit der Berechtigung write.

Ereignisse

Wie eine Zustellung aussieht

Jede Zustellung ist ein POST mit einem JSON-Body und diesen Headern:

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

Das data-Objekt hängt vom Ereignis ab:

• call.ended und message.taken: die obigen Anruffelder.
• call.started und call.transferred: call_id, direction, from, to, assistant_id, status und started_at.
• appointment.*: appointment_id, title, status, starts_at, ends_at, timezone, customer (Name, Telefon, E-Mail), contact_id, service, staff, call_id und notes.
• order.*: order_id, number, status, fulfillment, customer, address, items mit Optionen und Preisen, currency, subtotal, fee, total, source, call_id und, bei Stornierungen, cancel_reason.
• reservation.*: reservation_id, number, status, room, check_in, check_out, nights, adults, children, guest, currency, nightly, total und source.
• campaign.completed: campaign_id, name und die Fortschrittszahlen der Kampagne.

Hinweis: Bucht der Assistent während eines Anrufs einen Termin, können Sie appointment.booked zweimal erhalten. Eine wird beim Vornehmen der Buchung mit den Terminfeldern gesendet. Die andere wird gesendet, nachdem der Anruf zusammengefasst wurde, mit den Anruffeldern. Prüfen Sie, ob data appointment_id oder call_id enthält, und nutzen Sie das Feld id, um zu vermeiden, eine Zustellung zweimal zu verarbeiten.

Die Signatur prüfen

Die Signatur ist ein HMAC-SHA256 aus dem Zeitstempel, einem Punkt und dem rohen Request-Body, mit dem Signaturgeheimnis Ihres Endpunkts als Schlüssel. Sie wird als v1= gefolgt vom Hex-Digest gesendet.

1. Lesen Sie den rohen Body genau so, wie er empfangen wurde, vor jedem JSON-Parsing.
2. Bilden Sie die Zeichenkette {X-Ringhum-Timestamp}.{roher Body}.
3. Berechnen Sie das HMAC-SHA256 mit Ihrem Geheimnis und stellen Sie v1= voran.
4. Vergleichen Sie es mit X-Ringhum-Signature mittels eines zeitkonstanten Vergleichs.
5. Lehnen Sie die Anfrage ab, wenn der Zeitstempel mehr als fünf Minuten alt ist, um wiederholte Anfragen zu blockieren.

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

Antworten, Zeitüberschreitungen und Wiederholungen

• Antworten Sie mit einem beliebigen 2xx-Status, um die Zustellung zu bestätigen. Erledigen Sie langsame Arbeit erst, nachdem Sie geantwortet haben.
• Ringhum wartet bis zu 10 Sekunden auf Ihre Antwort.
• Antwortet Ihr Endpunkt nicht mit einem 2xx, wird die Zustellung insgesamt bis zu 3-mal versucht: sofort, erneut nach etwa 10 Sekunden, und ein letztes Mal etwa 60 Sekunden später. Danach wird sie verworfen.
• Zustellungen können außer der Reihe eintreffen. Nutzen Sie created_at und die IDs in data, um sie zu ordnen.

Die Tabelle Webhooks zeigt für jeden Endpunkt den letzten HTTP-Status und wann er gesendet wurde. Ein fehlschlagender Endpunkt bleibt aktiv; Ringhum schaltet ihn nicht für Sie ab.

Testen, pausieren und entfernen

• Test senden sendet sofort ein test.ping-Ereignis, und eine Meldung zeigt den HTTP-Status, den Ihr Endpunkt zurückgegeben hat.
• Der Schalter Aktiv pausiert einen Endpunkt. Ereignisse, die während der Pause auftreten, werden nicht nachträglich gesendet.
• Entfernen löscht den Endpunkt und sein Geheimnis.

Häufige Fragen

Was ist der Unterschied zu den Apps Zapier, Make und n8n unter Integrationen? Diese Verbindungen nutzen die Seite Integrationen und ihre sechs Ereignistypen. Ihr Body ist {"event", "workspace", "sent_at", "data"}, und wenn Sie ein Geheimnis festlegen, ist der Signatur-Header X-Ringhum-Signature: sha256=…, ein HMAC-SHA256 allein aus dem Body. Die hier beschriebenen Entwickler-Webhooks decken mehr Ereignisse ab und verwenden die v1=-Signatur mit Zeitstempel. Siehe Auswählen, was gesendet wird.

Mein Endpunkt gibt 2xx zurück, aber mein Code sieht nichts. Prüfen Sie, ob das Ereignis für diesen Endpunkt angehakt ist, ob der Endpunkt aktiv ist, und ob Ihre Firewall Anfragen aus dem Internet zulässt.

Warum schlägt die Signaturprüfung fehl? Meist wurde der Body vor dem Hashing geparst und neu kodiert. Hashen Sie die rohen Bytes genau so, wie sie empfangen wurden.