thomas-wiegold.com
Notion Workers for Small Business: A Hands-On Guide
Thomas Wiegold walks through building a production Shopify sync Worker — the source for the pacer and HMAC patterns in this tip.
3 patterns every production Notion Worker needs
Three built-in SDK and CLI patterns that close the most common production failure modes for Notion Workers: `worker.pacer()` smooths outbound API call rate to prevent 429s; HMAC-SHA256 signature verification secures webhook endpoints from spoofed payloads (with Notion's 5-failure auto-lock explained); and `--local`/`--preview` flags on `ntn workers sync trigger` let you iterate sync logic against real source data without writing a single row to your live Notion database.
Plan required: Notion Business or Enterprise ($20/user/month minimum). Workers are free through August 11, 2026, then billed via Notion Credits (~$0.0023/run). 1
Most Workers that break in production fail for one of three reasons: they flood an external API until it 429s, they accept webhook payloads from anyone who guesses the URL, or they write garbage to your live Notion database during a test run. The SDK has built-in answers to all three — they just aren't obvious until you hit the problem.
Prerequisites
| Requirement | Details |
|---|---|
| Notion plan | Business or Enterprise |
ntn CLI installed | curl -fsSL https://ntn.dev | bash |
Workers SDK (@notionhq/workers) | Installed via ntn workers init scaffolding |
| A deployed Worker with a Sync or Webhook capability | Any capability from the previous tips works |
| External API with rate limits (for pattern 1) | Shopify, GitHub, Stripe, etc. |
Loading link preview…
Pattern 1: Rate-limit outbound API calls with worker.pacer()
The problem: Notion runs multiple concurrent capabilities, and if two or more Workers share an external API token, their combined request rate easily overruns the API's quota. Shopify's standard plan allows 2 requests/second per store. 2 Without a guard, a backfill sync — where the Worker pages through hundreds of orders at once — will hit HTTP 429 within seconds.
The fix:
worker.pacer() is one of the six primitives in the Notion Workers SDK. 3 You declare a named budget with two parameters — allowedRequests (max calls per window) and intervalMs (window length in milliseconds) — then await handle.wait() before each outbound call. The SDK's server-side scheduler spreads the calls evenly across the window rather than letting them burst at the start. 3const shopify = worker.pacer("shopifyApi", {
allowedRequests: 2,
intervalMs: 1000,
});
// Before every external call:
await shopify.wait();
const orders = await fetchShopifyOrders(cursor);As Wiegold puts it: "The pacer spaces our calls across the window so we don't trip 429s during backfill or when running alongside other workers that share this pacer." 2
Gotcha: When multiple capabilities share the same pacer name, the server divides the budget across all concurrent executions. 3 If three capabilities each run and the pacer is set to
10/1000, each capability effectively gets ~3 requests/second. Set the budget to the per-process floor you can tolerate, not the maximum the API allows.Pattern 2: Verify webhook signatures with HMAC-SHA256
The problem: A Notion Workers webhook URL is a shared secret by itself — anyone holding the full URL can POST events and trigger your Worker. 4 For internal automations that's an acceptable risk; for anything that writes to Notion or invokes downstream actions, it isn't.
The fix: GitHub, Stripe, Shopify, and most mature webhook providers sign every payload with a shared secret and include the hex-encoded signature in a request header. Verify it before you process the body:
import { WebhookVerificationError } from "@notionhq/workers";
import * as crypto from "crypto";
export default worker.webhook("githubPush", async (event) => {
const secret = process.env.GITHUB_WEBHOOK_SECRET!;
const sig = event.headers["x-hub-signature-256"]?.replace("sha256=", "") ?? "";
const expected = crypto
.createHmac("sha256", secret)
.update(event.rawBody)
.digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
throw new WebhookVerificationError("Signature mismatch");
}
// Safe to process event.body from here
});Store the secret as a Worker environment variable: 4
ntn workers env set GITHUB_WEBHOOK_SECRET=your-secretWhy
timingSafeEqual matters: A plain string comparison (sig === expected) leaks timing information that lets an attacker brute-force the secret one character at a time. crypto.timingSafeEqual takes constant time regardless of where the strings diverge.Critical gotcha: Throwing
WebhookVerificationError tells Notion the payload was invalid — Notion will not retry it. 4 After 5 consecutive WebhookVerificationError failures, Notion blocks the webhook entirely and stops running the handler. The only way to unblock it is to redeploy the Worker. A successful run resets the counter, so test your secret rotation carefully.Loading link preview…
Pattern 3: Test sync logic without touching your live database
The problem: Every time you iterate on sync transformation logic, you risk writing partially-formatted or duplicate rows to your production Notion database. Deleting them manually is slow; letting them accumulate is worse.
The fix: The Notion CLI has two flags on
ntn workers sync trigger that are orthogonal but complementary: 5| Flag | What it does | Execution location |
|---|---|---|
--local | Runs your code via tsx on your machine; calls the external API for real | Local machine |
--preview | Executes the sync but does not write to the target Notion database | Local or remote |
Combine them for a fully safe iteration loop:
# Calls Shopify, transforms data, prints output — zero Notion writes:
ntn workers sync trigger shopifySync --local --preview
# When the output looks right, run without --preview to write for real:
ntn workers sync trigger shopifySync --localWiegold calls
--local "the most underrated" command in the Workers CLI: "It runs my code against Shopify but doesn't write to Notion, so I can dry-run, inspect transformed output, and fix bugs without polluting the database." 2Extra flags worth knowing:
--dotenv <path>— point to a specific.envfile for secrets (useful when you have dev vs. staging configs)--context <json>— pass in anextContextcursor from a previous--previewrun to continue pagination from a known offset, instead of replaying from the start 5ntn workers sync state reset <key>— wipe the sync cursor entirely; useful after a schema change that requires a full re-sync
Gotcha:
--local still calls the real external API. Shopify orders will actually be fetched; GitHub commits will actually be read. The guard is only on the Notion write side. If your external API charges per call or has a strict daily quota, factor that in before running a full backfill dry-run.Loading link preview…
Expected outcome
After adding these three patterns:
- Your Worker won't trip 429s from external APIs during backfill or when sharing a token across capabilities.
- Webhook endpoints reject payloads that don't carry a valid signature — and self-lock after 5 bad attempts rather than silently processing spoofed events.
- Sync logic can be iterated locally, against real source data, with zero risk of dirtying your production database.
These aren't optional polish — Wiegold's production Shopify Worker uses all three, and the official
makenotion/workers-template repo treats the 10 req/1000ms pacer and the --preview flag as defaults, not advanced options. 6 Add them before you cut your Worker to a production schedule.Cover image: AI-generated illustration
Add more perspectives or context around this Drop.