# Webhooks

> Keep your application in sync with Flipper Cloud using webhooks for instant feature flag updates.

## Overview

Webhooks notify your application instantly when feature flags change in Flipper Cloud. Instead of waiting for the next poll interval, your app receives a request telling it to sync — keeping feature state up to date within seconds of a change.

## How It Works

Each environment can have one or more webhooks. When a feature flag changes in that environment, Flipper Cloud sends an HTTP POST request to your webhook URL. Your application receives the request and syncs its local feature state with Cloud.

If you're using the Flipper client gem, webhook handling is built in. The gem exposes a webhook receiver endpoint that processes incoming webhooks and updates your local feature data automatically.

## Setup

1. Navigate to the environment you want to add a webhook to.
2. Go to **Settings** and click **New Webhook**.
3. Enter the URL where your application will receive webhook requests.
4. Copy the generated webhook secret for signature verification.

## Payload

Webhook requests are HTTP POST with a JSON body:

```json
{
  "environment_id": 123,
  "webhook_id": 456,
  "delivery_id": "467dd251-b5e9-44d1-b490-539a97ef0983",
  "action": "sync"
}
```

Each delivery has a unique `delivery_id` that can be used for idempotency — if your application receives the same `delivery_id` more than once, it can safely skip the duplicate.

## Signature Verification

Every webhook request includes a `Flipper-Cloud-Signature` header containing an HMAC-SHA256 signature. Use your webhook secret to verify the signature and confirm the request came from Flipper Cloud.

The signature header includes both the signature and a timestamp to protect against replay attacks.

## Retries

If your application returns a server error (5xx) or doesn't respond within 20 seconds, Flipper Cloud retries the delivery with exponential backoff. Retries continue for up to 13 attempts over approximately one day.

Client errors (4xx) are not retried — these indicate a problem with your endpoint configuration rather than a transient failure.

## Managing Webhooks

From the environment's settings page you can:

- **Enable/Disable** — Toggle a webhook on or off without deleting it.
- **Send Test** — Verify the webhook is working by sending a test request.
- **Regenerate Secret** — Generate a new signing secret if the current one is compromised.
- **View Delivery History** — See past deliveries with status, duration, and error details.

## Webhooks vs Polling

Your application can stay in sync with Flipper Cloud through either webhooks or polling:

- **Polling** checks for updates on an interval (configurable per plan). It's simpler to set up but introduces a delay between when a change is made and when your application sees it.
- **Webhooks** push updates to your application immediately. They require your application to be reachable from the internet but provide near-instant synchronization.

You can use both together. Polling acts as a safety net that catches any updates a webhook might miss, while webhooks ensure changes are reflected quickly.

Regardless of which approach you use, feature flag data is always stored and evaluated locally in your application. If Flipper Cloud is temporarily unreachable, your app continues working with the last known state. Read more about [how Flipper Cloud is designed to never take your app down](/blog/how-we-designed-flipper-cloud-to-never-take-your-app-down).