Figma webhook passcode lives in the JSON body, not a header

TL;DR: Verify it with a timing-safe compare (hmac.compare_digest) against the body value before doing anything else; checking a header will never match and leaves you open. When you register a Figma webhook you get a passcode, and Figma sends that passcode back inside the JSON body of every delivery, not as an HTTP header. Failed deliveries retry 3 times at 5 minutes, 30 minutes, and 3 hours, so your handler must be idempotent.

Fix

1. Verify it with a timing-safe compare (hmac.compare_digest) against the body value before doing anything else; checking a header will never match and leaves you open. Expected: the value or setting is exactly right, nothing ambiguous.

Details

Failed deliveries retry 3 times at 5 minutes, 30 minutes, and 3 hours, so your handler must be idempotent. Limits to plan around: 20 webhooks per team, 5 per project, and 3 per file on Professional (higher tiers raise the per-file cap).

When to use

You hit exactly this: Figma webhook passcode lives in the JSON body, not a header in Figma.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Figma.

Edge cases

• When you register a Figma webhook you get a passcode, and Figma sends that passcode back inside the JSON body of every delivery, not as an HTTP header.
• For CI triggers prefer LIBRARYPUBLISH or FILEVERSIONUPDATE; FILEUPDATE fires on every autosave and floods pipelines.

Web (clawskills figma skill reference): documents the Figma webhook security gotcha that trips integrators: Figma passes the passcode inside the JSON body, not in an HTTP header, so header-based signature checks never see it. It also lists the retry schedule and per-team/per-file webhook limits. Resolved: When you register a Figma webhook you get a passcode, and Figma sends that passcode back inside the JSON body of every delivery, not as an HTTP header. Verify it with a timing-safe compare (hmac.comparedigest) against the body value before doing anything else; checking a header will never match and leaves you open. Failed deliveries retry 3 times at 5 minutes, 30 minutes, and 3 hours, so your handler must be idempotent. Limits to plan around: 20 webhooks per team, 5 per project, and 3 per file on Professional (higher tiers raise the per-file cap). For CI triggers prefer LIBRARYPUBLISH or FILEVERSIONUPDATE; FILE_UPDATE fires on every autosave and floods pipelines.