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