Before you start
You need permission to manage organisation settings. Open Settings, then go to Developers and Webhooks.Webhooks appear only where they are enabled for your organisation. If the page
says webhooks are not enabled, contact support.
Add an endpoint
1
Start a new endpoint
Select Add an endpoint.
2
Enter the URL
The URL must use
https and be reachable from the internet. Use a tunnel
if you are still developing locally. Adclear also refuses a URL that
carries credentials or a fragment, or that points at an IP address or a
hostname it cannot resolve, and tells you which of those it was.3
Describe it
The description is optional and holds up to 200 characters. It appears
beside the URL in the endpoint list, which helps when you have several.
4
Choose the events
Pick Everything or Let me select individual events. A new endpoint
starts on Everything.
5
Add custom headers
Optional. Add a header name and value for anything your receiver needs, for
example a static token of its own.
6
Create it
Select Create endpoint. Adclear shows the signing secret once, on the
next screen. Copy it before you leave the page.
Choose which events to send
Everything sends every event, including ones Adclear adds later. Choosing individual events means you have to come back here when a new event you want appears. The individual events are grouped by what they are about, and the search box matches on the event name, its title and its description.The signing secret
Every request carries anAdclear-Signature header that your receiver checks
against the endpoint’s signing secret. Do not act on a request until that check
passes.
Adclear shows the secret once, when you create the endpoint, and cannot show it
again afterwards. On the endpoint page, the Signing secret row shows it
masked, as whsec_••••••••.
To replace a lost secret, open the endpoint and select Rotate secret in the
Signing secret row, or Rotate signing secret in the menu at the top of
the page. The current
secret stops working straight away, so deliveries fail their signature check
until you update your receiver with the new one. The new secret is also shown
once, in the same row.
Custom headers
Custom headers are sent with every request to that endpoint. A header cannot use a name Adclear sets itself, such asAdclear-Signature, Content-Type or
User-Agent, in any mix of upper and lower case. The endpoint is not saved
until that header is renamed or removed.
Give every header a name. If a row has a value but no name, the endpoint is not
saved and the row shows Give every header a name until you add one. A row
left completely empty is ignored.
Read the endpoint page
The top of the endpoint page shows the URL, its status and four numbers:- Success rate across the most recent finished deliveries. Deliveries still being retried are left out.
- Last successful delivery, or Never if nothing has got through yet.
- Failures in a row. Adclear switches the endpoint off when this reaches 20.
- Subscribed to, either All events or how many you picked.
Read the delivery log
The endpoint page lists its recent deliveries with the event, the outcome, how many attempts it took and when it started. Select a row, or move to it with the keyboard and press Enter, to open the delivery. It shows the request body Adclear sent and a timeline of every attempt: the status code your server returned, how long it took, and the response from your server. If Adclear could not reach your server at all, the attempt says so and why.
Two labels can appear beside an event:
- Resent marks a delivery you created with Resend. The original row stays as it was.
- Details deleted marks a delivery whose request and response bodies have passed the retention window.
What is kept, and for how long
Request and response bodies are kept for 7 days and then cleared. The delivery row itself stays, so the log remains readable: what goes is the content of the message. Resend replays the stored body, so it is available only while that body is still there. Once a delivery is marked Details deleted, resending it is no longer possible.Retries
Adclear makes up to 8 attempts for one delivery, spread over about 21 hours. The first attempts are close together so a brief outage is absorbed within minutes, and the later ones are further apart so a receiver that is down for the evening is still caught by the morning.Send a test event
Select Send a test event at the top of the endpoint page. The test takes the same path as a real event, signing and retries included, and appears in the delivery log like anything else, so what you see there is what production looks like. The test event is apromotion.created with all-zero ids and an obvious name,
so it cannot be mistaken for a real promotion in your system.
You cannot send a test event to an endpoint that is switched off. The button is
greyed out until you turn the endpoint back on.
Turn an endpoint off and on
Use the Active switch on the endpoint page to stop sending without deleting the endpoint. An inactive endpoint receives nothing. Adclear also switches an endpoint off by itself after 20 failed deliveries in a row. The endpoint page says which of the two happened, and the endpoint list marks it as switched off. To bring an endpoint back, fix your receiver and select Turn it back on. That also clears the run of failures, so the count starts again from zero.Delete an endpoint
Select Delete endpoint in the Danger zone at the bottom of the endpoint page, or in the menu at the top of the page. Deleting an endpoint stops its deliveries straight away and removes its delivery history with it. This cannot be undone. Switch the endpoint off instead if you want to keep the history.Related pages
Webhooks
Payloads, headers and signature verification for developers.
Settings
Other workspace and organisation settings.