Webhooks: scoco events in your own systems

Webhooks let scoco notify your own systems in real time — e.g. “call completed” or “appointment booked”. In the dashboard under Settings → Integrations → Automation you register an HTTPS address; scoco then sends a signed JSON message there for every event. Zapier, Make and n8n connect the same way (choose “Catch Hook” / “Webhook trigger” there and paste the generated URL into scoco).

Event types

Type	Fired when
`call.completed`	a call ended (with result, duration, caller number)
`call.summary_ready`	the AI summary of a call is available
`ticket.status_changed`	a call ticket was opened/resolved
`ticket.assigned`	a call ticket was assigned
`message.sms_received`	an SMS arrived at your scoco number
`message.sms_sent`	scoco sent an SMS
`appointment.booked`	the assistant booked an appointment
`contact.created`	a contact was created (manually or automatically from a call)

When creating an endpoint you can filter the types; without a filter you receive all of them. New types are added strictly additively — your receiver should simply ignore unknown types.

Message format

Every delivery is a POST with 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 differs per event type but always carries the relevant IDs — the dashboard shows the full details at any time. Fields inside data are also only ever added, never removed.

Verifying the signature (recommended)

When you create an endpoint, the dashboard shows a secret (whsec_…) exactly once. Store it safely — it cannot be retrieved again (if lost: delete the endpoint and create a new one).

Every delivery carries the header:

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

Verification: v1 is the HMAC-SHA256 (hex) of the string "<t>.<raw request body>", keyed with your secret. Reject messages whose t is older than ~5 minutes (replay protection).

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)

Delivery, retries, deactivation

Your endpoint counts as successful when it answers with a 2xx status within 10 seconds. Answer fast (ideally an immediate 200, processing asynchronous).
On failure scoco makes up to 5 delivery attempts in total (roughly 1 min → 5 min → 15 min → 1 h apart).
After 20 consecutive failures spanning at least 24 hours the endpoint is disabled automatically and the account owner is notified by e-mail. It can be re-enabled in the dashboard at any time; events that occurred while disabled are not re-delivered.
The delivery log of the last 30 days is visible in the dashboard (“Log”); older entries are deleted automatically.
“Test” delivers a signed ping event any time, to verify your setup.

Data protection

The messages contain personal data (caller numbers, names, call summaries). By registering an endpoint you instruct scoco to transmit this data to the system you named; make sure it is adequately protected there. Creating endpoints is therefore restricted to owners and administrators.