Webhooks

Webhook endpoints subscribe to selected Engage domain event types in one environment. Deliveries are persisted, claimed by workers, retried with backoff, and visible in the console.

Engage webhook endpoint inventory with status, health, subscribed events, attempts, failures, and delivery operations — Webhook inventory exposes endpoint health and durable attempt history before an operator opens a delivery.

Configure an endpoint

Provide an HTTPS URL, name, event types, optional custom headers, and retry policy:

maximum attempts;
initial backoff seconds;
request timeout seconds.

Endpoint status is active or paused. Health is never delivered, healthy, degraded, or failing based on delivery history and consecutive failures.

Engage webhook endpoint editor with URL, event selection, custom headers, signing secret, retry, and timeout policy — Endpoint authoring keeps event scope, authentication material, and retry behavior in one explicit contract.

Request headers


Content-Type: application/json
X-Engage-Delivery: DELIVERY_ID
X-Engage-Event: EVENT_TYPE
X-Engage-Timestamp: 1787047200
X-Engage-Signature: v1=HEX_HMAC_SHA256

The signing secret begins with engwhsec_ and is sensitive.

Verify the signature

Engage computes HMAC-SHA256 over:


X-Engage-Timestamp + "." + raw_request_body

Use the exact raw bytes received, compute HMAC with the endpoint signing secret, hex-encode it, and compare to the value after v1= using a constant-time comparison.

Also reject timestamps outside a short tolerance and deduplicate X-Engage-Delivery.

Pseudo-code:


timestamp = header("X-Engage-Timestamp")
expected = hex(hmac_sha256(secret, timestamp + "." + rawBody))
constant_time_equal("v1=" + expected, signatureHeader)

Response and retries

Return any 2xx status only after accepting the event durably. Non-2xx responses, timeouts, and network errors are retried according to endpoint policy. Your handler must be idempotent because a successful processing response can be lost.

Payload envelope

Webhook payloads include type, environment ID, occurrence time, and event-specific data. Use the event ID/delivery header for deduplication and tolerate additive fields.

Delivery operations

The console lists pending, processing, retrying, succeeded, and failed deliveries with attempt count, response code, latency, safe error, and next retry. Filter by endpoint, status, event, related resource, and time range when diagnosing.