Webhooks: Ereignisse aus scoco in Ihre Systeme

Mit Webhooks informiert scoco Ihre eigenen Systeme in Echtzeit über Ereignisse — z. B. „Anruf beendet" oder „Termin gebucht". Sie hinterlegen dazu im Dashboard unter Einstellungen → Integrationen → Automatisierung eine HTTPS-Adresse; scoco sendet dann für jedes Ereignis eine signierte JSON-Nachricht an diese Adresse. Auch Zapier, Make oder n8n verbinden Sie auf diesem Weg (dort „Webhook empfangen" / „Catch Hook" wählen und die generierte URL bei scoco eintragen).

Ereignistypen

Typ	Ausgelöst wenn
`call.completed`	ein Anruf beendet wurde (mit Ergebnis, Dauer, Anrufernummer)
`call.summary_ready`	die KI-Zusammenfassung eines Anrufs vorliegt
`ticket.status_changed`	ein Anruf-Ticket geöffnet/erledigt wurde
`ticket.assigned`	ein Anruf-Ticket zugewiesen wurde
`message.sms_received`	eine SMS bei Ihrer scoco-Nummer eingegangen ist
`message.sms_sent`	scoco eine SMS versendet hat
`appointment.booked`	der Assistent einen Termin gebucht hat
`contact.created`	ein Kontakt angelegt wurde (manuell oder automatisch aus einem Anruf)

Beim Anlegen eines Endpunkts können Sie die Typen filtern; ohne Filter erhalten Sie alle. Neue Typen kommen ausschließlich additiv hinzu — Ihr Empfänger sollte unbekannte Typen einfach ignorieren.

Format der Nachricht

Jede Zustellung ist ein POST mit Content-Type: application/json:

{
  "id": "5f0c…",
  "type": "call.completed",
  "created_at": "2026-08-06T12:58:41+00:00",
  "tenant_id": "a319…",
  "data": {
    "call_id": "…",
    "caller_e164": "+49621123456",
    "result": "message_taken",
    "duration_seconds": 151
  }
}

data ist je Ereignistyp verschieden, enthält aber immer die relevanten IDs — die vollständigen Details zeigt Ihnen jederzeit das Dashboard. Auch innerhalb von data kommen Felder nur additiv hinzu.

Signatur prüfen (empfohlen)

Beim Anlegen eines Endpunkts zeigt das Dashboard einmalig ein Secret (whsec_…). Speichern Sie es sicher — es ist danach nicht mehr abrufbar (bei Verlust: Endpunkt löschen und neu anlegen).

Jede Zustellung trägt den Header:

X-Scoco-Signature: t=1754481521,v1=5257a869e7…

Prüfung: v1 ist der HMAC-SHA256 (hex) über die Zeichenkette "<t>.<roher Request-Body>", geschlüsselt mit Ihrem Secret. Lehnen Sie Nachrichten ab, deren t älter als ~5 Minuten ist (Schutz vor Replay).

import hashlib, hmac, time

def verify(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, v1 = int(parts["t"]), parts["v1"]
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

Zustellung, Wiederholungen, Deaktivierung

Ihr Endpunkt gilt als erfolgreich, wenn er innerhalb von 10 Sekunden mit einem 2xx-Status antwortet. Antworten Sie schnell (idealerweise sofort 200, Verarbeitung asynchron).
Bei Fehlern versucht scoco die Zustellung bis zu 5-mal (Abstände ca. 1 Min → 5 Min → 15 Min → 1 Std).
Schlagen 20 Zustellungen in Folge über mindestens 24 Stunden fehl, wird der Endpunkt automatisch deaktiviert und der Konto-Inhaber per E-Mail informiert. Im Dashboard lässt er sich jederzeit wieder aktivieren; während der Deaktivierung angefallene Ereignisse werden nicht nachgeliefert.
Das Zustellprotokoll der letzten 30 Tage sehen Sie im Dashboard („Protokoll"); ältere Einträge werden automatisch gelöscht.
Mit „Testen" schicken Sie jederzeit ein signiertes ping-Ereignis zur Prüfung Ihrer Einrichtung.

Datenschutz

Die Nachrichten enthalten personenbezogene Daten (Anrufernummern, Namen, Gesprächszusammenfassungen). Mit dem Eintragen eines Endpunkts beauftragen Sie scoco, diese Daten an das von Ihnen benannte System zu übermitteln; sorgen Sie dort für angemessenen Schutz. Das Anlegen ist deshalb Inhabern und Administratoren vorbehalten.