Webhooks

The platform can POST signed events to one URL per workspace.

Today exactly one event exists: call.completed, emitted when an outbound phone task reaches a terminal state.There are no conversation, message, order or booking events yet. If your product needs to react to something a conversation did, it cannot subscribe to it — design around tools being called, and tell us what you need.

Verifying a delivery

Header, Stripe-style:

X-Tegain-Signature: t=1717171717,v1=<hex>
X-Tegain-Event: call.completed
X-Tegain-Delivery-Id: <uuid>

Signed string is {timestamp}.{raw body}, HMAC-SHA256 with the workspace webhook secret.

import hmac, hashlib

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

Verify against the raw bytes, not a re-serialised object. The platform signs exactly what it sends.

Delivery behaviour


Retries	3 attempts, backing off 60s / 5m / 30m
4xx	Permanent failure, no retry
5xx or timeout	Retried
Timeout	5 seconds
Replay window	5 minutes

Deliveries are listed in the dashboard and can be replayed by hand.

Webhooks require a plan that includes them; without it, events are silently not enqueued.

Get started

Building a tool server

Platform concepts

Platform API

Verifying a delivery

Delivery behaviour

​Verifying a delivery

​Delivery behaviour

Verifying a delivery

Delivery behaviour