Listen for status changes
Subscribe a URL to signed events, check each signature, run a receiver and use the delivery log when something is missed.
You end up with a receiver that gets our events, checks that they came from us and reads the current article when one changes. You can test it with a ping and send any delivery again.
Subscribe your URL
POST/api/v1/webhookswebhooks:manageYou can have up to 3 active subscriptions, on https URLs. Leave events out to receive every type, including ones added later.
curl -sS https://platform.charpstar.co/api/v1/webhooks \
-H "Authorization: Bearer $CHARPSTAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/charpstar/events", "events": ["asset.approved", "asset.images.updated"] }'The answer carries the signing secret once. Store it next to your API key, for example as CHARPSTAR_WEBHOOK_SECRET, and keep the id for the calls below.
Check the signature
Before you trust an event, check that it came from us and was not changed on the way. Read the raw request body as text before you parse it, and refuse the event if the signature differs or t is more than 300 seconds from your clock.
import { createHmac, timingSafeEqual } from "node:crypto";
// CharpstAR-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + "." + raw body)>
export function verifyCharpstarSignature(header, rawBody, secret, toleranceSeconds = 300) {
if (!header || !secret) return false;
let t = null;
const signatures = [];
for (const part of header.split(",")) {
const [k, ...rest] = part.trim().split("=");
const v = rest.join("=");
if (k === "t" && /^\d+$/.test(v)) t = Number(v);
else if (k === "v1" && /^[0-9a-f]{64}$/i.test(v)) signatures.push(v.toLowerCase());
}
if (t === null || signatures.length === 0) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSeconds) return false;
const expected = Buffer.from(createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"));
return signatures.some((s) => {
const got = Buffer.from(s);
return got.length === expected.length && timingSafeEqual(got, expected);
});
}Run the complete receiver
The same checks as the reference client, in one file you can run with Node 18 or later. It answers 200 once it has handled an event and skips a delivery it has already handled, because retries carry the same CharpstAR-Delivery id.
// node receiver.mjs (Node 18 or later)
// Set CHARPSTAR_API_KEY and CHARPSTAR_WEBHOOK_SECRET first.
import { createServer } from "node:http";
import { verifyCharpstarSignature } from "./verify.mjs";
const secret = process.env.CHARPSTAR_WEBHOOK_SECRET;
const handled = new Set(); // use your database in production
async function handle(event) {
const delivered = event.type === "status.changed" && event.data.to === "delivered";
if (event.type === "asset.approved" || event.type === "asset.images.updated" || delivered) {
// Events are a signal: read the current asset, then write the links back into your system.
const res = await fetch(`https://platform.charpstar.co/api/v1/assets/${encodeURIComponent(event.article)}`, {
headers: { Authorization: `Bearer ${process.env.CHARPSTAR_API_KEY}` },
});
if (!res.ok) throw new Error(`asset read failed: ${res.status}`);
const asset = await res.json();
console.log(asset.articleId, asset.status, asset.arUrl);
}
}
createServer(async (req, res) => {
if (req.method !== "POST" || req.url !== "/charpstar/events") return res.writeHead(404).end();
const chunks = [];
for await (const chunk of req) chunks.push(chunk);
const raw = Buffer.concat(chunks).toString("utf8"); // the raw body: verify before parsing
if (!verifyCharpstarSignature(req.headers["charpstar-signature"], raw, secret)) {
return res.writeHead(401).end();
}
const delivery = req.headers["charpstar-delivery"];
if (handled.has(delivery)) return res.writeHead(200).end(); // a retry of one we already handled
try {
const event = JSON.parse(raw);
if (event.type !== "ping") await handle(event);
handled.add(delivery);
res.writeHead(200).end();
} catch (err) {
console.error(err);
res.writeHead(503).end(); // not handled: we will send it again later
}
}).listen(8080);Send a test event
POST/api/v1/webhooks/{webhook_id}/testwebhooks:manageThis queues a signed ping event to the subscription. It is sent within about a minute, signed like any other event.
curl -sS -X POST https://platform.charpstar.co/api/v1/webhooks/$WEBHOOK_ID/test \
-H "Authorization: Bearer $CHARPSTAR_API_KEY"Read the delivery log and send one again
GET/api/v1/webhooks/{webhook_id}/deliverieswebhooks:manageThe log holds every delivery of the last 30 days, newest first, with attempts and your receiver's answers.
curl -sS https://platform.charpstar.co/api/v1/webhooks/$WEBHOOK_ID/deliveries \
-H "Authorization: Bearer $CHARPSTAR_API_KEY"A delivery is sent again with the same body and the same CharpstAR-Delivery id, so your receiver skips it if it has already handled it.
curl -sS -X POST https://platform.charpstar.co/api/v1/webhooks/$WEBHOOK_ID/deliveries/$DELIVERY_ID/redeliver \
-H "Authorization: Bearer $CHARPSTAR_API_KEY"