CalSpark developer docs

List endpoints take limit (1 to 100, default 25) and cursor. Pass the previous response's next_cursor to get the next page. Cursors are opaque and signed; a bad one returns 400 invalid_cursor.

{ "object": "list", "data": [ ... ], "has_more": true, "next_cursor": "eyJ2Ijox..." }

Lists are newest first. GET /events is oldest first for polling, and always returns a next_cursor when it returns events, so you can resume exactly where you stopped. New events show up after a short settle delay of about two seconds.

Register endpoints in Settings, Developers or with POST /api/v1/webhook-endpoints. The signing secret (whsec_...) is shown once. Every delivery is a POST with a JSON event envelope and these headers:

CalSpark-Signature: t=1760000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Compute HMAC SHA-256 over `${t}.${rawBody}` using your secret, hex encode it, and compare it to each v1 value in constant time. During secret rotation the header carries one v1 per active secret; accept the request if any matches. Reject timestamps more than 5 minutes from your clock. Always verify against the raw request body, before any JSON parsing.

const crypto = require('crypto');

// secrets: your endpoint signing secret(s). Pass both the new and the old secret while rotating.
function verifyCalSparkSignature(rawBody, header, secrets, toleranceSeconds = 300) {
  const parts = String(header || '').split(',');
  let timestamp = null;
  const signatures = [];
  for (const part of parts) {
    const i = part.indexOf('=');
    if (i === -1) continue;
    const key = part.slice(0, i).trim();
    const value = part.slice(i + 1).trim();
    if (key === 't' && timestamp === null) timestamp = Number(value);
    if (key === 'v1') signatures.push(value);
  }
  if (!Number.isInteger(timestamp) || signatures.length === 0) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > toleranceSeconds) return false;

  let ok = false;
  for (const secret of secrets) {
    const expected = crypto.createHmac('sha256', secret).update(timestamp + '.' + rawBody).digest('hex');
    for (const sig of signatures) {
      const a = Buffer.from(sig, 'utf8');
      const b = Buffer.from(expected, 'utf8');
      if (a.length === b.length && crypto.timingSafeEqual(a, b)) ok = true;
    }
  }
  return ok;
}

// Express: use the RAW body, not the parsed JSON.
// app.post('/calspark', express.raw({ type: 'application/json' }), (req, res) => {
//   const valid = verifyCalSparkSignature(req.body.toString('utf8'), req.get('CalSpark-Signature'), [process.env.CALSPARK_WEBHOOK_SECRET]);
//   if (!valid) return res.sendStatus(400);
//   const event = JSON.parse(req.body.toString('utf8'));
//   res.sendStatus(200);
// });
module.exports = { verifyCalSparkSignature };