Partner API task
Signed calls
Check a call really came from us.
When you save an API key in the task, every call we make to your endpoint is signed with it. Checking the signature tells you the call came from us and its body was not changed on the way. It is optional: an endpoint that only reads x-api-key keeps working. The request itself is on Request and answer.
Headers
| Header | Value |
|---|---|
x-giftedstock-timestamp | When we made the call, in unix seconds. |
x-giftedstock-signature | HMAC-SHA256 of "<timestamp>.<body>" under your key, in hex. |
- The key is the API key you saved in the task, the same one we send in x-api-key.
- The body is the raw request body, byte for byte as it arrived. Sign what you received, never JSON you parsed and wrote again.
- The dot between the timestamp and the body is part of the signed text.
Check it in Node
import { createHmac, timingSafeEqual } from "node:crypto";
const KEY = process.env.GIFTEDSTOCK_TASK_KEY; // the key you saved in the task
/** True when the call is ours: `raw` is the request body exactly as received. */
export function fromGiftedStock(headers, raw) {
const ts = headers["x-giftedstock-timestamp"];
const sig = headers["x-giftedstock-signature"];
if (!ts || !sig) return false;
// refuse an old call replayed later: pick the window you are comfortable with
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const want = createHmac("sha256", KEY).update(`${ts}.${raw}`).digest("hex");
const a = Buffer.from(want, "hex");
const b = Buffer.from(String(sig), "hex");
return a.length === b.length && timingSafeEqual(a, b);
}Call it before you read the body as JSON. If it returns false, answer anything but 200 or 400: the participant then sees that your API did not answer, not that the task failed.
The time window is yours to choose; 300 seconds above is an example. Compare signatures with a constant-time check, as above, never with
===.Keeping the key safe
- You type the key once in the campaign form. We keep it sealed on our server and the form shows only that a key is saved.
- A saved key is sent only to the exact endpoint it was saved with. Point the task at another endpoint and you type the key again.
- Nobody who opens the campaign sees your endpoint or your key.