Receive a webhook
Stop polling. Let Akedly tell your server when something happens.
Building the endpoint, verifying a signature, and watching a delivery land.
What you need
- A URL your server answers on — a tunnel to localhost is fine while developing
- A pipeline, either OTP or utility
- Ten minutes
Steps
1. Write the endpoint. Answer 200 first, then do your work:
Express
app.post('/webhooks/akedly', (req, res) => {
res.sendStatus(200) // acknowledge immediately
handle(req.body) // then process
})
Requests are abandoned after 10 seconds, so a handler that writes to a database and calls two services before answering is recorded as a failure even though your code worked.
2. Point the pipeline at it. Paste the URL into the pipeline's Webhooks section and save. Leaving it empty disables outbound webhooks entirely.
View in dashboardPipelines → WebhooksSet the webhook URL and reveal the signing secret.
3. Test it before real traffic exists. The dashboard can fire a sample request and show your server's live response.
The test body is not a real body
The "event": "webhook.test" markers apply to ordinary OTP/widget pipeline test sends.
Utility pipeline test sends are the exception: the dashboard delivers a real-shaped
message.status envelope. Use the test to prove your server is reachable — but write your
parsing against the real payloads.
4. Verify the signature. Utility webhooks are always signed. Verify against the raw bytes — if your framework parses the JSON and you re-encode it before checking, key order can shift and every signature fails. The Webhooks page has the algorithm and per-language examples, and the utility webhook studio will generate a real signature you can test against.
When it breaks
- Every signature fails — you are almost certainly verifying a re-serialised object. Capture the raw body first.
- Nothing arrives at all — check which product you are on. Utility webhooks retry five times and keep a delivery log; widget and OTP callbacks send once, with no retry and no history.
- You built a verifier for OTP callbacks — those are never signed. There is nothing to verify; match the
transactionIDagainst your own record instead.
Where to go next
- Webhooks — how the three webhook systems differ
- Utility Webhooks — the three utility events in full