Webhooks

Webhooks send HTTP POST requests to your server whenever flags change, so you can react to changes in real time.

Verifying Signatures

Validate webhook authenticity with HMAC-SHA256

Reliability & Troubleshooting

Retry behavior, auto-disable rules, and debugging failed deliveries

Slack Integration

Send flag change notifications to a Slack channel

How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Dashboard     │     │   Flipswitch    │     │  Your Endpoint  │
│                 │     │     Server      │     │                 │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         │  1. Update flag       │                       │
         │──────────────────────>│                       │
         │                       │                       │
         │                       │  2. POST (signed)     │
         │                       │──────────────────────>│
         │                       │                       │
         │                       │  3. 200 OK            │
         │                       │<──────────────────────│
         │                       │                       │

A resource is created, updated, or deleted in the dashboard or via the API
Flipswitch sends a signed HTTP POST to each subscribed webhook endpoint
Your endpoint processes the event and returns a 2xx response

Event Types

Flags

Event Type	Trigger
`flag.created`	A feature flag is created
`flag.updated`	Flag metadata is updated
`flag.deleted`	A feature flag is deleted
`flag.rules.created`	Rules are created for a flag in an environment
`flag.rules.updated`	Existing rules are updated for a flag in an environment

Environments

Event Type	Trigger
`environment.created`	An environment is created
`environment.updated`	An environment is updated
`environment.deleted`	An environment is deleted

Segments

Event Type	Trigger
`segment.created`	A segment is created
`segment.updated`	A segment is updated
`segment.deleted`	A segment is deleted

API Keys

Event Type	Trigger
`apikey.rotated`	An API key is rotated

Projects

Event Type	Trigger
`project.updated`	Project settings are updated

HTTP Delivery Format

Each webhook delivery is an HTTP POST request with the following headers and body.

Request Headers

Header	Description
`Content-Type`	`application/json`
`User-Agent`	`Flipswitch/1.0`
`X-Flipswitch-Event-Id`	Unique event identifier (UUID)
`X-Flipswitch-Delivery-Id`	Unique delivery identifier for this attempt
`X-Flipswitch-Event-Type`	Event type (e.g., `flag.rules.updated`)
`X-Flipswitch-Signature`	HMAC-SHA256 signature (`sha256=<hex>`) for verification
`X-Flipswitch-Timestamp`	Unix epoch seconds when the delivery was signed
`Cache-Control`	`no-cache`

Any custom headers configured on the webhook are also included.

Request Body

{
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "eventType": "flag.rules.updated",
  "occurredAt": "2025-01-15T10:30:42Z",
  "eventVersion": 1,
  "payloadSchemaVersion": 1,
  "payload": {
    "org": { "id": 1, "name": "Acme" },
    "project": { "id": 10, "name": "Core App" },
    "environment": { "id": 100, "name": "Production" },
    "flag": { "id": 55, "key": "dark-mode", "name": "Dark Mode" },
    "before": { "enabled": false },
    "after": { "enabled": true }
  }
}

Field	Description
`eventId`	Unique event identifier
`eventType`	The type of event that occurred
`occurredAt`	When the event happened (ISO 8601)
`eventVersion`	Event schema version
`payloadSchemaVersion`	Payload schema version
`payload`	Event-specific data

Environment Filter

When creating a webhook, you can optionally restrict it to a specific environment. This controls which events the webhook receives:

No filter (all environments). The webhook receives all flag events for the project.
Specific environment. The webhook only receives events scoped to that environment.

Most events are project-scoped and are delivered regardless of environment filter. flag.rules.created, flag.rules.updated, environment.created, environment.updated, environment.deleted, and apikey.rotated are environment-scoped and respect the environment filter.

Creating a Webhook

Navigate to Webhooks

Go to your Project and select Webhooks from the sidebar.

Configure the Endpoint

Click Create Webhook and enter your endpoint URL. This must be an HTTPS URL that accepts POST requests.

Optionally add custom headers (e.g., an authorization token for your endpoint).

Select Events

Choose which event types this webhook should receive. You can subscribe to any combination of events across flags, environments, segments, API keys, and projects.

Choose Scope

Select whether the webhook applies to all environments or a specific environment.

Save

Click Save. Flipswitch generates a signing secret for the webhook automatically. Copy the secret now — you'll need it to verify signatures.

Secret Rotation

You can rotate a webhook's signing secret without downtime:

Rotate. Click Rotate Secret on the webhook. A new secret is generated, and both the old and new secrets are valid during a 24-hour grace period.
Update your endpoint. Deploy your new secret and verify it works.
Complete rotation. Click Complete Rotation to revoke the old secret immediately, or let it expire after the grace period.

To cancel a rotation and revert to the original secret, click Abort Rotation.

During rotation, the X-Flipswitch-Signature header contains two sha256= entries — one signed with the new secret and one with the old. Your verification code should accept either. See Handling Secret Rotation.

Testing

Use the Send Ping button on any saved webhook to send a test webhook.ping event. This bypasses the delivery queue and sends immediately, so you can verify your endpoint is reachable and signature verification works before subscribing to real events.

Verifying Signatures

Reliability & Troubleshooting

Slack Integration

On this page