Overview & Signatures

Supported Webhook Events

• flag.created — Dispatched when a new feature flag definition is added.
• flag.updated — Dispatched when toggle state, rollout percentage, description, or target lists are modified.
• flag.enabled — Dispatched when a flag is toggled on.
• flag.disabled — Dispatched when a flag is toggled off.
• flag.archived — Dispatched alongside flag.disabled when a flag is turned off.
• flag.rollout_changed — Dispatched when the rollout percentage changes.
• flag.target_users_updated — Dispatched when the target users list changes.
• flag.deleted — Dispatched when a flag is permanently removed from an environment.
• flag.rollback — Dispatched when a configuration changes via rollback to a snapshot.
• project.updated — Dispatched when project settings are modified.
• project.deleted — Dispatched when a project is deleted.
• apikey.rotated — Dispatched when an API key is rotated.

You can also send a ping test event to any configured webhook endpoint from the dashboard to verify connectivity.

Cryptographic Signature Verification

To prevent spoofing, FlagPilot signs each webhook delivery with an HMAC-SHA256 signature computed from the delivery timestamp and the raw JSON payload, using the webhook endpoint's signing secret. The hex-encoded signature is sent in the X-FlagPilot-Signature header, alongside X-FlagPilot-Event (the event type) and X-FlagPilot-Timestamp (ISO-8601). Verify the signature like this:

const crypto = require('crypto');

const expectedSignature = crypto
  .createHmac('sha256', signingSecret)
  .update(`${timestampHeader}.${rawBodyString}`)
  .digest('hex');

// Compare against the X-FlagPilot-Signature header using a
// constant-time comparison (e.g. crypto.timingSafeEqual).

Timeout & Retry Policy

FlagPilot enforces a 5-second connection timeout per delivery attempt. Retries only trigger on a network error or a 500/502/503/504 response — any other non-2xx status is treated as a permanent failure and is not retried. Up to 4 attempts total, with fixed delays between each:

• 1st Attempt: Immediate trigger
• 2nd Attempt: After 5 seconds delay
• 3rd Attempt: After 30 seconds delay
• 4th Attempt: After 2 minutes delay

Delivery history is retained per your plan: 1 day on Free, 30 days on Solo, 90 days on Pro, and 365 days on Business.

FAQ