> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adclear.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Legacy webhooks

> The webhooks Adclear sets up for you during onboarding, with their payloads, signature check and what to do when a delivery is missed.

> [!NOTE]
>
> This page is for webhooks the Adclear team set up for your organisation
> during onboarding. They keep working exactly as they do today. If you add
> endpoints yourself under **Settings**, **Developers**, **Webhooks**, see
> [Webhooks](https://docs.adclear.ai/developer/webhooks.md) instead. The two use different events,
> payloads, headers and signatures.

## Overview

These 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. If signing is enabled for your organisation, you also receive a shared secret to verify that requests came from Adclear.

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 best-effort, and expect occasional repeats. Acknowledge quickly with `2xx`, then process asynchronously. For `evaluation-completed`, see [Missed or failed deliveries](#missed-or-failed-deliveries).
* 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).

```json theme={null}
{
  "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`, `conditionally_approved` or `risk_accepted`), optional `rationale` |
| `review.changes_requested` | `decidedByUserId`, `decision` (`changes_requested`), optional `rationale` |
| `review.rejected` | `decidedByUserId`, `decision` (`rejected`), optional `rationale` |

## Signature verification

If Adclear has set a signing secret for your organisation, each 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 webhook requests:

| Header | Description |
| - | - |
| `Content-Type` | `application/json` |
| `X-Webhook-Signature` | `sha256=<hex>` HMAC-SHA256 of the raw body. Present when a signing secret is set |
| `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:

```json theme={null}
{
  "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](#reply-to-an-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](https://docs.adclear.ai/developer/comments.md#import-comments) 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](https://docs.adclear.ai/developer/comments.md#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.

## Missed or failed deliveries

### Evaluation results

An `evaluation-completed` webhook can arrive late, arrive with a failed result, or not arrive at all. Each situation below says what you see and what to do.

| Situation | What you see | What to do |
| - | - | - |
| The evaluation failed | A webhook with `status: "failed"`, an empty `issues` array and `reviewRequired: false` | Treat it as no result, not a pass. [Re-trigger the evaluation](https://docs.adclear.ai/developer/evaluation.md#trigger-evaluation) or send the version for manual review |
| Your endpoint returned a non-`2xx` response, took longer than 30 seconds, or could not be reached | No result in your system | Adclear does not send the webhook again. [Poll the evaluation](https://docs.adclear.ai/developer/evaluation.md#poll-evaluation-status) to get the result |
| Adclear could not send the webhook on the first attempt | A late webhook, sometimes more than once | Adclear tries again every 10 minutes. Deduplicate on `evaluationId` |
| The evaluation has not finished | No webhook. Adclear sends it only when the evaluation finishes | Poll the evaluation. If it is still `processing` after 5 minutes, follow [evaluation troubleshooting](https://docs.adclear.ai/developer/evaluation.md#troubleshooting) |
| Adclear set a signing secret, but the request has no `X-Webhook-Signature` header | An unsigned request | Reject it and contact Adclear |

Only treat a result as a pass when `status` is `succeeded` and `reviewRequired` is `false`. An empty `issues` array is not enough on its own, because a succeeded result can require review with no issues listed.

### Recovery endpoints

If you miss a webhook, get the current state from the Public API. These endpoints return the latest state, not a replay of missed events.

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

### Reporting a failure to Adclear

Send these details so that Adclear can trace the webhook:

* `evaluationId`, plus the `correlationId` from the evaluate response
* `promotionId` and `promotionVersionId`
* The `X-Correlation-ID` header, if you received the request
* When you expected the webhook (in UTC), and what your endpoint returned

## 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 | If Adclear gave you a signing secret, verify `X-Webhook-Signature` before processing |

For cross-cutting errors (401, 403, 429, 502), see [Errors & rate limits](https://docs.adclear.ai/developer/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.