Client Setup - Flinks Documentation

At a glance


Request	`POST` to your URL, `Content-Type: application/json; charset=utf-8`
Signature	`X-Webhook-Signature: sha256=<HEX>`, HMAC-SHA256 of the raw body with your secret

1. Get set up with Flinks

Send your Flinks contact the HTTPS URL that will receive the events. Provide one per environment (sandbox and production). In return you receive a webhook secret, used to verify every event. Store it like a password, for example in a secrets manager or environment variable, never in source control. Keep sandbox and production secrets separate.

2. Verify the signature

Every request carries X-Webhook-Signature: sha256=<HEX>. Check it before trusting the body.

Compute HMAC-SHA256 over the raw request body bytes, keyed with your secret (UTF-8). Do not parse and re-serialize the JSON first: the bytes must match exactly.
The hex in the header is uppercase. Compare case-insensitively and in constant time.
Respond 401 if it does not match.
Optional replay protection: when is part of the signed body, so you can reject events older than a few minutes.

Example: Node.js (Express)

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.FLINKS_WEBHOOK_SECRET;

app.post("/webhooks/flinks", express.raw({ type: "application/json" }), (req, res) => {
  const received = (req.get("X-Webhook-Signature") ?? "").toLowerCase();
  const expected = "sha256=" +
    crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");

  const a = Buffer.from(received);
  const b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body.toString("utf8"));
  res.sendStatus(200); // ack first: there are no retries
  handleEvent(event);  // then process (queue, background job, ...)
});

app.listen(3000);