Webhooks

Webhooks deliver Adclear events to your endpoint as soon as they happen, so you do not have to poll. You provide an HTTPS URL during onboarding and receive a shared secret for verifying that requests genuinely came from Adclear.

Overview and configuration

Webhooks are configured per organisation by the Adclear team during onboarding.

Event	Trigger
`evaluation-completed`	An evaluation finishes (success or failure)
`comment.created`	A comment is added to a promotion version
`review.submitted`	A promotion version is submitted for review
`review.approved`	A terminal approval decision is recorded
`review.changes_requested`	A reviewer requests changes
`review.rejected`	A promotion version is rejected

Delivery:

Sent as application/json via POST.
Treat delivery as at-least-once and best-effort. Acknowledge quickly with 2xx, then process asynchronously.
Deduplicate lifecycle events on deliveryId. Deduplicate evaluation-completed on evaluationId.

Common lifecycle envelope

The five review lifecycle events share this envelope. evaluation-completed keeps its existing flat payload (documented below).

{
  "event": "review.approved",
  "deliveryId": "uuid",
  "occurredAt": "2026-01-15T10:00:00.000Z",
  "promotionId": "uuid",
  "versionId": "uuid",
  "data": {}
}

Field	Description
`event`	Event name (matches `X-Adclear-Event`)
`deliveryId`	Unique delivery ID for idempotency
`occurredAt`	ISO timestamp for when the action happened
`promotionId`	Parent promotion (campaign) ID
`versionId`	Specific promotion version ID
`data`	Event-specific payload (see below)

Lifecycle `data` fields

Event	`data` fields
`comment.created`	`commentId`, `threadId`, `authorUserId`, `content`, `isComplianceComment`
`review.submitted`	`submittedByUserId`, optional `reviewerUserId`
`review.approved`	`decidedByUserId`, `decision` (`approved` or `conditionally_approved`), optional `rationale`
`review.changes_requested`	`decidedByUserId`, `decision` (`changes_requested`), optional `rationale`
`review.rejected`	`decidedByUserId`, `decision` (`rejected`), optional `rationale`

Signature verification

Every request includes an X-Webhook-Signature header: an HMAC-SHA256 hex digest of the raw request body, prefixed with sha256=. Verify it before processing the payload. Use the raw bytes, not a re-serialised object. Headers on every webhook:

Header	Description
`Content-Type`	`application/json`
`X-Webhook-Signature`	`sha256=<hex>` HMAC-SHA256 of the raw body
`X-Adclear-Event`	Event type, for example `review.submitted`
`X-Correlation-ID`	Internal trace ID for support requests

Evaluation payload reference

evaluation-completed uses the legacy payload shape below (not the lifecycle envelope). It may include routing metadata such as organizationId and workspaceId. Example:

{
  "promotionId": "promo-uuid-...",
  "promotionVersionId": "version-uuid-...",
  "evaluationId": "eval-uuid-...",
  "status": "succeeded",
  "reviewRequired": true,
  "overallAssessment": "This promotion requires review",
  "issues": [],
  "metadata": { "workfrontProjectId": "PROJ-123" }
}

If an evaluation webhook does not arrive, fall back to polling the evaluation.

Recovery endpoints

If a lifecycle webhook is missed, read current authoritative state from the Public API. These endpoints return the latest state, not a replay of missed events.

Resource	Endpoint
Comments	`GET /v1/promotions/{promotionId}/versions/{versionId}/comments`
Decision	`GET /v1/promotions/{promotionId}/versions/{versionId}/decision`
Evaluation	`GET /v1/promotions/{promotionId}/versions/{versionId}/evaluation`

Endpoint requirements

Requirement	Detail
Protocol	HTTPS only
Response time	Respond `2xx` within 30 seconds
Idempotency	Deduplicate lifecycle events on `deliveryId`; deduplicate evaluations on `evaluationId`
Signature	Verify `X-Webhook-Signature` before processing

For cross-cutting errors (401, 403, 429, 502), see Errors & rate limits.

Get started

Fundamentals

Adclear API

File API

Overview and configuration

Common lifecycle envelope

Lifecycle `data` fields

Signature verification

Evaluation payload reference

Recovery endpoints

Endpoint requirements

​Overview and configuration

​Common lifecycle envelope

​Lifecycle data fields

​Signature verification

​Evaluation payload reference

​Recovery endpoints

​Endpoint requirements

Overview and configuration

Common lifecycle envelope

Lifecycle `data` fields

Signature verification

Evaluation payload reference

Recovery endpoints

Endpoint requirements