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": [
    {
      "recommendation": "Consider adding a risk warning.",
      "rationale": "Financial promotions must include risk warnings per FCA guidelines.",
      "severity": "HIGH",
      "commentId": "comment-uuid-...",
      "citedRules": [
        { "id": "rule-uuid-...", "name": "Risk Warning Requirement", "product": "Investment", "channel": "Digital" }
      ],
      "location": { "type": "text", "content": "Invest now for guaranteed returns", "pageNumber": 1 }
    }
  ],
  "metadata": { "workfrontProjectId": "PROJ-123" }
}

Issue fields

Field	Description
`recommendation`	Suggested change to resolve the issue
`rationale`	Why the issue was raised
`severity`	`LOW`, `MEDIUM`, or `HIGH`
`commentId`	Optional. Root comment ID of the issue’s thread. Use it to reply to the issue
`citedRules`	Optional. Rules the issue is based on
`location`	Optional. Where the issue was found in the content

Reply to an issue

Comment-backed issues normally include a commentId: the ID of the root comment that anchors the issue’s thread. Send it as parentCommentId when importing a reply with POST /v1/promotions/{promotionId}/versions/{versionId}/comments. Your reply threads onto the issue instead of creating a new thread. Two caveats:

Treat commentId as optional. A replayed delivery may omit it. When it is absent, resolve the thread with Get comments instead.
Comment indexing is asynchronous. If a reply sent immediately after the webhook is rejected with PARENT_NOT_FOUND, wait briefly and retry.

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

Issue fields

Reply to an issue

Recovery endpoints

Endpoint requirements

​Overview and configuration

​Common lifecycle envelope

​Lifecycle data fields

​Signature verification

​Evaluation payload reference

​Issue fields

​Reply to an issue

​Recovery endpoints

​Endpoint requirements

Overview and configuration

Common lifecycle envelope

Lifecycle `data` fields

Signature verification

Evaluation payload reference

Issue fields

Reply to an issue

Recovery endpoints

Endpoint requirements