Skip to Content

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:manage

You 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.

verify.mjs
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.

receiver.mjs
// 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:manage

This 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:manage

The 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"
POST/api/v1/webhooks/{webhook_id}/deliveries/{deliveryId}/redeliverwebhooks:manage

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"

On this page