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/jsonviaPOST. - Treat delivery as best-effort, and expect occasional repeats. Acknowledge quickly with
2xx, then process asynchronously. Forevaluation-completed, see Missed or failed deliveries. - Deduplicate lifecycle events on
deliveryId. Deduplicateevaluation-completedonevaluationId.
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 anX-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 acommentId: 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
commentIdas 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
Anevaluation-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 thecorrelationIdfrom the evaluate responsepromotionIdandpromotionVersionId- The
X-Correlation-IDheader, 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.