pigeon#

a little carrier pigeon that ferries Figma LIBRARY_PUBLISH events to a Discord channel webhook. Cloudflare Worker. coalesces per-asset-type events into a single Discord embed inside a 60s window via a Durable Object (one DO instance per file_key). one retry at +5 min on Discord failure, then drop.

stack: Cloudflare Workers + Durable Objects (SQLite storage + alarms) + Workers KV. no external services, no runtime deps.

prerequisites#

Cloudflare account. Workers Free is sufficient.
Figma team admin access + personal access token with webhooks:write scope.
Discord channel incoming webhook url.
bun installed (https://bun.sh). swap to npm/pnpm by editing package.json scripts if needed.

setup#

all commands run from the repo root.

copy config template:
```
cp wrangler.toml.example wrangler.toml
```
install deps:
```
bun install
```
authenticate with Cloudflare (one-time):
```
bunx wrangler login
```

(optional) pin deploys to a specific Cloudflare account:

export CLOUDFLARE_ACCOUNT_ID=<account-id>   # from `bunx wrangler whoami`

create KV namespace. paste the returned id into wrangler.toml under [[kv_namespaces]]:
```
bunx wrangler kv namespace create FIGMA_DISCORD_WEBHOOK
```

map your Figma file_key to the Discord webhook url:

bunx wrangler kv key put --binding=FIGMA_DISCORD_WEBHOOK --remote \
  "<FIGMA_FILE_KEY>" "<DISCORD_WEBHOOK_URL>"

(optional) bind a custom domain. uncomment and edit the [[routes]] block in wrangler.toml:
```
[[routes]]
pattern = "figma.example.com"
custom_domain = true
```
the parent zone must already exist on this Cloudflare account.
deploy:
```
bun run deploy
```
note the deployed url (either <name>.<subdomain>.workers.dev or your custom domain).
set the passcode secret (random string, used for auth between Figma and Worker):
```
openssl rand -hex 32 | bunx wrangler secret put FIGMA_PASSCODE
```
save the same value; step 10 uses it.

curl -X POST \
  -H "X-FIGMA-TOKEN: <FIGMA_PAT>" \
  -H "Content-Type: application/json" \
  "https://api.figma.com/v2/webhooks" \
  -d '{
    "event_type": "LIBRARY_PUBLISH",
    "team_id": "<FIGMA_TEAM_ID>",
    "endpoint": "<WORKER_URL>/figma",
    "passcode": "<SAME_PASSCODE_AS_STEP_9>",
    "description": "Design system publish -> Discord"
  }'

Figma sends PING immediately. Worker returns 200; no Discord message is posted for PING.

test: publish a library change in Figma. Discord message arrives ~60s later.

endpoints#

POST /figma — Figma webhook receiver. validates passcode. accepts PING and LIBRARY_PUBLISH. other event types return 200 and are ignored.
GET /health — returns {"status":"healthy","lastFigmaRequestAt":<iso>|null} as JSON with 200. lastFigmaRequestAt is the ISO timestamp of the most recent authenticated Figma webhook delivery, useful for detecting upstream silence.

all other routes return 404.

opt-out#

include #exclude (case-insensitive) anywhere in the Figma publish description. Worker drops the event.

key / value reference#

FIGMA_FILE_KEY: path segment in figma.com/file/<KEY>/… or figma.com/design/<KEY>/….
FIGMA_TEAM_ID: path segment in figma.com/files/team/<ID>/….
CLOUDFLARE_ACCOUNT_ID: from bunx wrangler whoami.
DISCORD_WEBHOOK_URL: Discord channel → edit channel → integrations → webhooks → new webhook.
FIGMA_PAT: Figma → settings → security → personal access tokens. scope: webhooks:write.

files#

src/index.ts — fetch handler, passcode check, route to Batcher DO.
src/batcher.ts — Durable Object. merges items by key, schedules 60s alarm, flushes to Discord, one retry on failure.
src/discord.ts — embed builder + POST. respects Discord field limits (1024 char value, 15 items per field).
src/figma.ts — payload types, isExcluded(), figmaFileUrl(), collectChanged().
src/types.ts — Env, BatchState, BatchItems, LibraryItem.

config knobs#

in src/batcher.ts:

BATCH_WINDOW_MS = 60_000 — coalescing window from first event.
RETRY_DELAY_MS = 300_000 — delay before single retry on Discord failure.
MAX_FLUSH_ATTEMPTS = 2 — total attempts (initial + retry). higher values risk loops.

in src/discord.ts:

MAX_ITEMS_PER_FIELD = 15
FIELD_VALUE_MAX = 1024

Figma event handling#

input: Figma LIBRARY_PUBLISH payload. separate events fire per asset type (components, styles, variables) within milliseconds of each other. all three categories are merged into one batch per file_key via env.BATCHER.idFromName(file_key).

output: one Discord embed per batch window. fields: components (N), styles (N), variables (N). each field lists up to 15 item names; overflow renders as "+ X more". deleted items are not shown.

limits#

Figma: 20 webhooks per team. team-context webhooks do not fire for invite-only project files.
Discord: 1024 chars per field value, 6000 chars per embed total. enforced in src/discord.ts.
Workers Free: ample for typical design system publish frequency.

debugging#

live logs:

bun run tail

Figma webhook delivery history (last 7 days):

curl -H "X-FIGMA-TOKEN: <PAT>" \
  "https://api.figma.com/v2/webhooks/<WEBHOOK_ID>/requests"

list webhooks on a team:

curl -H "X-FIGMA-TOKEN: <PAT>" \
  "https://api.figma.com/v2/teams/<TEAM_ID>/webhooks"

delete a webhook:

curl -X DELETE -H "X-FIGMA-TOKEN: <PAT>" \
  "https://api.figma.com/v2/webhooks/<WEBHOOK_ID>"

typecheck source:

bun run typecheck

local dev (needs a tunnel to receive Figma webhooks):

cp .dev.vars.example .dev.vars   # fill in FIGMA_PASSCODE
bun run dev

acknowledgements#

inspired by bryanberger/figma-discord-webhook. the #exclude opt-out convention is borrowed from that project. no code was copied.

license#

MIT. see LICENSE.

Configure Feed