A game is only worth running if its results end up somewhere useful. The winner has to reach whoever ships the prize. The coupon has to reach your loyalty system. The play has to reach your CRM. Keliplay sends all of that to you as webhooks: an HTTPS POST to an endpoint you choose, as soon as something happens.
The trouble with any webhook is that your endpoint is a public URL. If someone finds it, they can send it whatever they like, including a very convincing “you have a winner” message. So every request we send is signed, and your backend should refuse anything that isn’t.
What we send
There are three events, and each one arrives as the same small envelope: a type, a createdAt timestamp and a data object.
session_completedfires when a play has finished and been scored, win or not. It carries the campaign, the session, your player reference, the outcome and the score.winner_selectedfires when a draw picks winners, whether you ran it by hand or it ran on a schedule. It lists each winner with their rank and prize. Replaying the same draw does not send it twice.reward_grantedfires when a coupon is handed out, either at the end of a play or to a drawn winner.
One detail in that last event is deliberate. The payload never contains the coupon code itself. It carries the grant id, and your backend fetches the code from the API with its own key. A leaked webhook log shouldn’t be a leaked stack of codes.
Test plays from the dashboard don’t send webhooks, so you can try a campaign without your CRM filling up with your own name.
How the signature works
Each endpoint gets its own secret when you create it. It starts with whsec_, and it is shown once, at creation. Copy it into your secrets store then, because the dashboard won’t show it again.
Every delivery carries three headers:
X-Keliplay-Signature, in the formt=<unix seconds>,v1=<hex>X-Keliplay-Event, the event typeX-Keliplay-Delivery-Id, unique to that delivery
The v1 value is an HMAC-SHA256 of the timestamp, a dot and the raw request body, keyed with your endpoint secret. To check it, you do the same sum and compare:
// Verify before you trust it. Node, with the raw request body.
import { createHmac, timingSafeEqual } from 'node:crypto'
function verify(rawBody, header, secret, toleranceSec = 300) {
const { t, v1 } = Object.fromEntries(
header.split(',').map((p) => p.split('=')))
if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false
const expected = createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest('hex')
return v1.length === expected.length &&
timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
}
Three things in that function matter more than they look.
Use the raw body. Most frameworks parse JSON before your handler runs. If you verify against the re-serialised object, the bytes can differ from what we signed, and valid requests will fail. Keep the body exactly as it arrived.
Check the timestamp. Because the timestamp is part of what we sign, nobody can change it without breaking the signature. That lets you reject old requests, so a captured delivery can’t be replayed next week. Five minutes is a sensible window. The choice is yours.
Compare in constant time. timingSafeEqual takes the same time whether the first character matches or the last one does, so response timing gives nothing away.
Retries and repeats
Deliveries are at least once. If your endpoint is down or slow, we try again, which also means you can occasionally see the same delivery twice. Keep a note of the X-Keliplay-Delivery-Id values you have handled and skip any you have already seen.
A delivery is tried up to five times in all. Each attempt waits up to ten seconds for your response, and the gap between attempts grows each time, starting at five seconds. Timeouts, network errors, any 5xx, a 408 and a 429 are all retried. Any other 4xx is treated as a final answer: if your endpoint says the request is bad, sending it again won’t change that.
The practical rule is to answer quickly. Verify the signature, store the event, return a 2xx, and do the slow work afterwards.
Scoping and addresses
An endpoint can listen to everything, or only to certain campaigns or channels. Scoping by channel follows whatever campaign is live on it, so an endpoint for your app’s channel keeps working as campaigns change.
Endpoints must be HTTPS on a public address. We check that when you register the endpoint and again on every delivery, so a hostname that later starts pointing somewhere private stops receiving events.
Changing a secret
There’s no rotate button yet. To change a secret, create a second endpoint with the same URL and scope, deploy code that accepts either secret, then delete the old endpoint. For a moment you’ll get each event twice, and the delivery id check from earlier takes care of that.