Webhooks

FlagBridge can send webhook events to your endpoints when flags change.

Auth: Admin key required.

Events

Event	Trigger
flag.created	A new flag was created
flag.updated	Flag settings changed (name, rules, enabled state)
flag.deleted	A flag was deleted
flag.enabled	A flag was enabled
flag.disabled	A flag was disabled

POST /v1/projects/:projectSlug/webhooks

Register a webhook endpoint.

curl -X POST https://api.flagbridge.io/v1/projects/my-app/webhooks \
  -H "Authorization: Bearer fb_admin_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/flagbridge",
    "events": ["flag.enabled", "flag.disabled", "flag.updated"],
    "secret": "your-webhook-secret"
  }'

Webhook payload

{
  "id": "evt_abc123",
  "event": "flag.enabled",
  "projectSlug": "my-app",
  "environment": "production",
  "timestamp": "2026-03-31T20:00:00.000Z",
  "data": {
    "flagKey": "new-checkout-flow",
    "previousState": { "enabled": false },
    "currentState": { "enabled": true }
  }
}

Signature verification

FlagBridge signs webhook payloads with HMAC-SHA256 using your webhook secret.

import { createHmac } from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}

// In your Express handler
app.post('/webhooks/flagbridge', (req, res) => {
  const signature = req.headers['x-flagbridge-signature'] as string;
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET!
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process event
  const event = req.body;
  console.log(`Flag ${event.data.flagKey} was ${event.event}`);

  res.status(200).send('OK');
});

Retries

FlagBridge retries failed deliveries with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours

After 4 failed retries, the event is marked as failed and no further attempts are made.

Delivery logs

# List recent deliveries
curl https://api.flagbridge.io/v1/webhooks/wh_abc123/deliveries \
  -H "Authorization: Bearer fb_admin_YOUR_KEY"

# Redeliver a failed event
curl -X POST https://api.flagbridge.io/v1/webhook-deliveries/del_abc123/redeliver \
  -H "Authorization: Bearer fb_admin_YOUR_KEY"