Skip to main content
Webhooks send Adclear events to your endpoint as soon as they happen, so you do not have to poll. You add and manage endpoints yourself under Settings, Developers, Webhooks. Each one gets its own signing secret, a delivery log with the request and response of every attempt, a resend action and a test event. See Set up webhooks for the screens themselves.
If the Adclear team set up a webhook for you during onboarding, it works differently. See Legacy webhooks.

Event catalogue

See Webhook events for each event’s payload, and Webhook recipes for worked examples in Zapier, Slack and Jira. A key is never renamed and never reused for a different meaning. A changed meaning is a new key. Subscribing to * rather than a list means every event, including ones added later. It is a subscription value only and never appears as an event type.

Envelope

Delivery is at-least-once and events are not guaranteed to arrive in the order they happened. A retry can land after a later event, and two events about the same promotion can arrive either way round. Order events by occurredAt, and use id and deliveryId to drop any you have already processed. Adclear rejects an event with an unrecognised top-level field rather than dropping it, so the envelope cannot widen by accident. A serialised event is at most 256 KB.

Headers

Any custom headers you configure on the endpoint are sent as well. A custom header cannot use the name of any header in the table above. Names are compared without regard to case, so adclear-signature is refused too, and the endpoint is not saved until the header is renamed or removed.

Verify the signature

v1 is an HMAC-SHA256 hex digest of <t>.<raw body>, keyed with the endpoint’s signing secret, including its whsec_ prefix. Because the timestamp is part of the signed string it cannot be altered on its own, so checking t against your own clock gives you replay protection. Reject a delivery whose timestamp is more than five minutes from your clock. Sign the raw bytes you received, not a re-serialised object.
Unknown keys in the header are ignored, so a future v2= can be added without breaking a receiver that only reads v1.

Delivery and retries

Adclear switches an endpoint off after 20 failed deliveries in a row, and its settings page says so. Fix the receiver, then turn the endpoint back on from that page, which also clears the run of failures. A test event goes through the same delivery path as a real one. It cannot be sent to an endpoint that is switched off: turn the endpoint back on first. Request and response bodies in the delivery log are kept for 7 days and then cleared. The log rows stay. Resending a delivery replays the stored body, so it is possible only inside that window.

Missed deliveries

If a delivery never succeeds, get the current state from the Public API. See Recovery endpoints. They return the latest state, not a replay of the events you missed.