Webhooks

The platform POSTs signed events to your endpoints. A workspace on the legacy path has one URL; on /api/v2 you manage several through /api/v2/webhooks/endpoints, each with its own secret and its own subscription list. Those operations are in the Runtime API reference.

What actually fires

Twenty-three event types are emitted by the platform today:

Resource	Events
Conversations	`conversation.created` · `handoff.requested`
Messages	`message.received` · `message.sent` · `message.delivered` · `message.read` · `message.failed` · `message.deleted`
Templates	`template.status_changed`
Leads	`lead.hot` · `lead.verification_requested`
Documents	`document.ready` · `document.failed`
Extractions	`extraction.completed` · `extraction.failed`
Reports	`report.completed` · `report.failed`
Knowledge	`knowledge.ingestion.completed` · `knowledge.ingestion.failed`
Jobs	`job.completed` · `job.failed` · `job.cancelled`
Calls	`call.completed`

The catalogue is larger than that, and the difference still matters. GET /api/v2/webhooks/catalogue/ returns 32 event types. Nine are registered and never emitted: conversation.completed, the agent.run.* family, document.processing.started, knowledge.updated, call.started, call.failed and usage.threshold_reached.Two of those are easy to miscount. call.failed appears in the platform’s source only as an inbound name — one of the events the telephony provider sends us — and is never emitted outward. document.processing.started has no call site at all.Those seven are declarations of intent, not promises you can build on. Subscribing to one is accepted and you will simply never hear from it. Do not put a timeout around waiting for one.

Read the catalogue from code rather than hardcoding a list. It is the one source that moves when the platform does, and an event graduating from declared to emitted is not something you will be told about.

Verifying a delivery

X-Impel-Signature: t=1717171717,v1=<hex>
X-Impel-Event: document.ready
X-Impel-Event-Id: <stable per event>
X-Impel-Delivery-Id: <unique per attempt>
X-Impel-Attempt: 1

X-Impel-Signature is canonical. X-Tegain-Signature is sent alongside it with an identical value, for receivers configured before the Impel Labs rename — a signature check that starts failing looks, from your side, exactly like a webhook that stopped arriving. Signed string is {timestamp}.{raw body}, HMAC-SHA256 with the endpoint secret.

The header can carry more than one v1. During a secret rotation we sign with both keys, so a parser that keeps only one value rejects every delivery for the length of the overlap window — which is precisely when you are least able to afford it. Accept if any v1 matches.

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    ts, sigs = "", []
    for part in header.split(","):
        key, _, value = part.partition("=")
        if key.strip() == "t":
            ts = value.strip()
        elif key.strip() == "v1":          # several during a rotation
            sigs.append(value.strip())
    if not ts or not sigs:
        return False
    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 any(hmac.compare_digest(expected, s) for s in sigs)

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

The v1 prefix versions the scheme, not the key. A future v2= can appear beside it, and a parser that ignores prefixes it does not know keeps working.

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

Be idempotent on X-Impel-Event-Id. It is stable across our retries, so a receiver keyed on it is safe against both an honest retry and a captured replay — and we retry deliberately, so every correct receiver needs this anyway. X-Impel-Delivery-Id changes per attempt and is the right key only if you want to detect an exact replay. Deliveries are readable and replayable through the API — GET /api/v2/webhooks/deliveries, and replay by delivery or by event — as well as from the dashboard.

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

Get started

Building a tool server

Platform concepts

Platform API

What actually fires

Verifying a delivery

Delivery behaviour

​What actually fires

​Verifying a delivery

​Delivery behaviour

What actually fires

Verifying a delivery

Delivery behaviour