API & webhooks

curl -X POST "https://templater.nestutils.com/v1/pdfs/render?wait=20" \
  -H "Authorization: Bearer $TEMPLATER_KEY" \
  -H "Idempotency-Key: invoice-KA-26-27-09-77" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "invoice-pdf",
    "fileName": "KA-26-27-09-77.pdf",
    "data": { "invoice_number": "KA/26-27/09/77", "items": [ … ] }
  }'

curl https://templater.nestutils.com/v1/pdfs/01M3CDJKX8RWAYVCGWRJ2H5MRW \
  -H "Authorization: Bearer $TEMPLATER_KEY"

# → { "data": { "id": "…", "status": "rendered", "failureReason": null,
#               "result": { "fileName": "…", "url": "https://…", "expiresAt": "…", … } } }

# 1. Ask for an upload slot (valid 15 minutes)
curl -X POST https://templater.nestutils.com/v1/uploads \
  -H "Authorization: Bearer $TEMPLATER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fileName": "invoices.csv", "bytes": 1048576 }'
# → { "data": { "uploadId": "01M3…", "url": "https://…", "method": "PUT",
#               "headers": { "content-type": "text/csv", … }, "expiresAt": "…" } }

# 2. PUT the file to that URL with exactly those headers
curl -X PUT "<url>" -H "content-type: text/csv" --data-binary @invoices.csv

# 3. Start the batch
curl -X POST https://templater.nestutils.com/v1/pdfs/batch \
  -H "Authorization: Bearer $TEMPLATER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template": "invoice-pdf", "uploadId": "01M3…", "zip": true }'

# 4. Follow it
curl https://templater.nestutils.com/v1/batches/<batchId> -H "Authorization: Bearer $TEMPLATER_KEY"

to,customer.first_name,invoice.number,invoice.items
priya@example.com,Priya,INV-0142,"[{""name"":""Widget"",""qty"":2}]"
arjun@example.com,Arjun,INV-0143,"[{""name"":""Gadget"",""qty"":1}]"

{
  "data": {
    "id": "01M3CE…",
    "kind": "pdf",
    "status": "running",
    "templateSlug": "invoice-pdf",
    "versionRef": "live",
    "isTest": false,
    "fileName": "invoices.csv",
    "columns": ["to", "customer.first_name", "invoice.number", "invoice.items"],
    "counters": { "rows": 1000, "valid": 998, "invalid": 2, "succeeded": 640, "failed": 0, "pending": 358 },
    "errorsUrl": "https://…/errors.csv?…",
    "zipUrl": null,
    "failureReason": null,
    "createdAt": "2026-09-25T13:00:00.000Z",
    "finishedAt": null
  }
}

# The HTML itself, ready to open or paste — no JSON escaping:
curl -X POST https://templater.nestutils.com/v1/templates/invoice-issued/preview \
  -H "Authorization: Bearer $TEMPLATER_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/html" \
  -d '{ "data": { "customer": { "first_name": "Priya" } } }' > invoice.html

# A PDF template as the file:
curl -X POST https://templater.nestutils.com/v1/templates/invoice-pdf/preview \
  -H "Authorization: Bearer $TEMPLATER_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/pdf" \
  -d '{ "data": { "invoice": { "number": "INV-0142" } } }' > invoice.pdf

POST /your/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Templater-Webhooks/1
Templater-Signature: t=1790341512,v1=5f2b0c…e91a

{
  "id": "evt_01M3CDS0Q3N6G9WJ4Z7R2K8B5T",
  "type": "pdf.rendered",
  "createdAt": "2026-09-25T13:05:12.402Z",
  "data": {
    "message": {
      "id": "01M3CDJKX8RWAYVCGWRJ2H5MRW",
      "kind": "pdf",
      "status": "rendered",
      "isTest": false,
      "templateSlug": "invoice-pdf",
      "versionNumber": 3,
      "to": [],
      "idempotencyKey": null,
      "renders": [
        {
          "role": "primary",
          "fileName": "KA-26-27-09-77.pdf",
          "pageCount": 2,
          "sizeBytes": 184233,
          "url": "https://…/KA-26-27-09-77-01M3CDJKX8….pdf?X-Amz-Signature=…",
          "expiresAt": "2026-09-26T13:05:10.000Z"
        }
      ],
      "createdAt": "2026-09-25T13:05:04.118Z"
    }
  }
}

{
  "id": "evt_…",
  "type": "render.failed",
  "createdAt": "…",
  "data": {
    "message": { "id": "…", "kind": "pdf", "status": "failed", … },
    "reason": "Template error: \"items\" is not iterable"
  }
}

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.TEMPLATER_WEBHOOK_SECRET; // whsec_…

// Verify against the RAW body — re-serialised JSON will not match.
app.post('/webhooks/templater', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('Templater-Signature') ?? '';
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(parts.t);
  const expected = crypto.createHmac('sha256', SECRET).update(`${t}.${req.body}`).digest('hex');

  const fresh = Math.abs(Date.now() / 1000 - t) <= 300;
  const valid = parts.v1 && expected.length === parts.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
  if (!fresh || !valid) return res.status(400).send('bad signature');

  const event = JSON.parse(req.body.toString('utf8'));
  // Deduplicate on event.id, then do the work asynchronously.
  if (event.type === 'pdf.rendered') {
    const [file] = event.data.message.renders;
    console.log('PDF ready', file.fileName, file.url);
  }
  res.sendStatus(200); // answer fast: any 2xx within 10 s counts as delivered
});