Skip to main content
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 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. 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.
  • 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).

Lifecycle data fields

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:

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:

Issue fields

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.

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. 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.

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

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