Webhooks

A webhook is how Akedly tells your server that something happened — a message was delivered, a customer replied, a verification finished. You give us a URL, and we send a message to it.

What is a webhook?

Normally you call us: you send a request, we send a response. A webhook is the other direction — something happens on our side, and we call you.

The alternative is polling: asking us "has it delivered yet?" every few seconds. That is slow and wasteful. With a webhook you find out the moment it happens.

In practice a webhook is just an HTTP POST to a URL you own. If you can handle a form submission, you can handle a webhook:

app.post('/webhooks/akedly', (req, res) => {
  res.sendStatus(200)   // 1. say "got it" immediately
  handle(req.body)      // 2. then do your work
})

What Akedly can send you

Authentication has two webhook paths and they do not behave the same way. Which applies depends on how you integrate.

Both send once. There is no retry and no delivery record on either, so neither should be your only record of a verification — confirm anything that matters from the API. For idempotency, use a stable identifier from the payload: transactionID in the V1/V1.2 mainTransaction object, or widgetAttempt.attemptId for V2.

Setting up your endpoint

Your webhook URL lives on the pipeline, in its Webhooks section. Paste a URL, save, and we start sending. Leave it empty and we send nothing.

The same section holds your signing secret — the value you need to prove a message came from us.

Use HTTPS even though HTTP is accepted

The dashboard asks for an HTTPS endpoint, and a plain http:// URL is in fact accepted too. Send them over HTTPS anyway: webhook bodies carry personal data, and on the OTP API the verification code itself.

Try it before you have traffic

The dashboard can fire a sample request at your URL and show you exactly what your server replied — useful long before any real traffic exists.

Open Test your endpoint in the Webhooks section, check the headers and body we will send, press Send, and the response panel shows your server's live answer.

The test body is not a real body

The sample begins with "event": "webhook.test" and "test": true. Those markers do not appear in ordinary V1, V1.2 or V2 Widget callbacks. Utility pipeline test sends are the exception: the dashboard sends a real-shaped message.status envelope instead. Use the test to prove your server is reachable and answers 200 — but write your parsing against the real payloads, not against this sample.

Why webhooks are signed

Your callback URL lives on the public internet. Anyone who learns it — through logs, browser network tabs, mistyped DNS, a leaked screenshot — can POST forged payloads to it claiming a verification succeeded. Without a signature check, your application has no way to tell a real Akedly webhook from a fake one.

Signing solves this. Akedly hashes the request body together with a timestamp and a unique message ID, using a secret only you and Akedly know. You re-compute the hash on your side; if it matches, the request is genuine and untampered.

Where to find your secret

Each pipeline has its own signing secret, prefixed with whsec_. To retrieve it:

1. Open your pipeline in the dashboard
2. Scroll to the Webhooks section
3. Click View signing secret

The secret looks like this:

whsec_kU3+tF2dG8XzL9pQrSvT4Bh6jYwMnRb1cZxK7eNoAi0=

Treat it like a password. Store it in your environment, never commit it, and rotate it if you suspect exposure.

The signed headers

Every signed webhook arrives with three headers:

svix-id:        msg_2N4kJpQrSvT4Bh6jYwMnRb1cZx
svix-timestamp: 1745190600
svix-signature: v1,kU3+tF2dG8XzL9pQrSvT4Bh6jYwMnRb1cZxK7eNoAi0=

The svix-signature value contains one or more space-separated entries, each in the form v1,<base64>.

Webhook contract

Signing algorithm

If you're using one of the official Svix SDKs (next section), you don't need to implement this — it's here for reference and for any stack without an SDK.

1. Decode the secret:
     key = base64_decode( secret.replace("whsec_", "") )

2. Build the signed payload:
     signed = "${svix-id}.${svix-timestamp}.${raw_body}"

3. Compute the expected signature:
     expected = base64_encode( HMAC_SHA256(key, signed) )

4. Split svix-signature on spaces. For each entry, strip the `v1,` prefix before the
   constant-time compare with the computed base64 value. If any match, the request is valid.

5. Reject if | svix-timestamp − now | > 5 minutes (replay protection).

The raw_body is the unparsed request body bytes — don't JSON.parse then re-serialize, or you'll lose the exact byte sequence the signature was computed over.

Verify in your stack

Pick your language. The signing algorithm is identical across all of them — these snippets just wrap the math.

// npm install svix
const { Webhook } = require('svix')

const wh = new Webhook(process.env.AKEDLY_WEBHOOK_SECRET)

// rawBody must be the unparsed string body — not req.body (parsed JSON).
// In Express, mount express.raw({ type: 'application/json' }) on this route.
wh.verify(rawBody, req.headers) // throws WebhookVerificationError if invalid

Common pitfalls

Rotating the secret

If a secret leaks — or just on a routine schedule — click Regenerate in the pipeline's Webhooks section. Akedly issues a new whsec_... and immediately starts signing webhooks with it.