Handling deliveries

When an event occurs that your app is subscribed to, Stok.ly will send a HTTP request to the URL you provided. This page describes how to handle that request.

Request Headers

Each delivery contains the following HTTP headers:

Verifying the request

You should verify each webhook delivery to ensure it came from Stok.ly. This can be done by generating a signature from the subscription secret, the timestamp header & the request body.

Here is an example written in NodeJS using the node:crypto library:

const signatureHeader = request.headers["x-stokly-signature"];
const timestampHeader = request.headers["x-stokly-timestamp"];

if (!signatureHeader || !timestampHeader) {
  sendJson(response, 400, { 
    error: "Missing required headers (x-stokly-signature, x-stokly-timestamp)" 
  });
  return;
}

const secret = "_aWG2kSLAZjcxLaL13tIYfHh4JrwuZakJquV56xBcXg"
const rawBody = await readRequestBody(request);
const expected = crypto
  .createHmac("sha256", secret)
  .update(`${timestampHeader}.${rawBody}`)
  .digest("hex");

const received = signatureHeader.replace("sha256=", "");

const valid = crypto.timingSafeEqual(
  Buffer.from(expected, "hex"),
  Buffer.from(received, "hex")
);

if (!valid) {
  sendJson(response, 400, { error: "Invalid signature" });
  return;
}

// signature verified - start your own logic


// return a 200
sendJson(response, 202, {});

Sending a response

Stok.ly considers any 2xx response status as successful. Any other status codes will be treated as an error and will be retried according to our retry logic that is detailed below.

Your server must respond within 5 seconds, otherwise the request will time out.

Retries

Failed requests will be retried a maximum of 15 times with increasing delays

After each failed delivery attempt, the next request is delayed as follows

If 3 consecutive deliveries reach the maximum number of retries, the webhook subscription will be automatically disabled.