Identity webhooks allow you to integrate Flagsmith with your own data warehouse or analytics infrastructure. The integration automatically sends flag evaluations for identified users to a URL you specify whenever an identity's flags are evaluated via the Get Identity Flags endpoint.

This is particularly useful for:

• Analytics processing: Enriching your analytics data with flag states and segment memberships
• Cohort analysis: Segmenting users based on the flags they saw
• A/B testing: Tracking which variants users received for experiment analysis

The process is as follows:

Integration Setup

1. Write an endpoint that accepts the JSON schema defined below.
2. Add the integration in Flagsmith, providing your URL created in the step above.
3. You can also provide a Secret which will be hashed and included in the HTTP header. This will allow you to verify that the Webhook has come from Flagsmith.
4. All API calls generated by the Flagsmith SDK to the Get Identity Flags endpoint will send a full set of flag evaluations, traits and segments for that particular user to your webhook URL.

Webhook JSON Schema

Flagsmith will send a POST request to the Webhook url you provide, with the following payload in the body:

{
 "flags": [
  {
   "enabled": false,
   "environment": 2,
   "feature": {
    "created_date": "2022-02-04T14:57:39.200798Z",
    "default_enabled": false,
    "description": null,
    "id": 1,
    "initial_value": null,
    "name": "12e12e",
    "type": "STANDARD"
   },
   "feature_segment": null,
   "feature_state_value": null,
   "id": 2,
   "identity": null
  },
  {
   "enabled": true,
   "environment": 2,
   "feature": {
    "created_date": "2022-02-04T14:57:44.244575Z",
    "default_enabled": true,
    "description": null,
    "id": 2,
    "initial_value": null,
    "name": "gggg",
    "type": "STANDARD"
   },
   "feature_segment": null,
   "feature_state_value": null,
   "id": 4,
   "identity": null
  }
 ],
 "identity": "user_test",
 "segments": [
  {
   "id": 1,
   "member": true,
   "name": "test_segment"
  }
 ],
 "traits": [
  {
   "id": 4,
   "trait_key": "222",
   "trait_value": 333
  },
  {
   "id": 5,
   "trait_key": "aaa",
   "trait_value": "bbb"
  }
 ]
}

Use Case

Once the integration has been set up, you can start segmenting your data warehouse users based on the flags that they saw and the segments that they are a member of. This allows you to enrich the data within your warehouse through Flagsmith.

For example, you might use identity webhooks to:

• Send flag evaluation data to analytics platforms like Amplitude or Mixpanel for cohort analysis
• Track which A/B test variants users received for experiment analysis
• Build custom dashboards that correlate flag states with user behaviour

Webhook Signature

When your webhook secret is set, Flagsmith uses it to create a hash signature with each payload. This hash signature is passed with each request under the X-Flagsmith-Signature header that you need to validate at your end

Validating Signature

Compute an HMAC with the SHA256 hash function. Use request body (raw utf-8 encoded string) as the message and secret (utf8 encoded) as the Key. Here is one example in Python:

import hmac

secret = "my shared secret"

expected_signature = hmac.new(
    key=secret.encode(),
    msg=request_body,
    digestmod=hashlib.sha256,
).hexdigest()

received_signature = request["headers"]["x-flagsmith-signature"]
hmac.compare_digest(expected_signature, received_signature) is True