Skip to main content

Custom Webhook Integration

Receive feature flag change events in any system via HTTP(S) POST with signed payloads.

What you get​

  • Event payloads for flag lifecycle changes (created, status changed, rollout updated, deleted).
  • Batched delivery format (an events array) even for single changes.
  • HMAC-SHA256 signatures with timestamp to verify authenticity.
  • Metrics surfaced in Toggly for deliveries, errors, and latency.

Configure in Toggly​

  1. Go to Integrations → Add Integration → Webhook.
  2. Choose the environment, enter your HTTPS endpoint, and optionally supply a signing secret (else we generate one).
  3. Select which events to send.
  4. Save. The secret is shown once—store it securely.
  5. Use “Send Test Webhook” from the integration page to validate end-to-end.

Delivery format​

We send a concise payload (no signature field in the body):

{
  "ApplicationId": "b904c975-895b-4bca-894c-13e50599c7cc",
  "Environment": "Production",
  "Features": {
    "Diagnostics": [
      {
        "Name": "AlwaysOn",
        "Parameters": null
      }
    ],
    "Samples": [
      {
        "Name": "AlwaysOn",
        "Parameters": null
      }
    ]
  }
}

Signing and verification​

Headers included:

  • X-Toggly-Signature: v1=<hex> where hex = HMACSHA256(secret, "<timestamp>.<body>") (signature is only in the header)
  • X-Toggly-Timestamp: UNIX seconds
  • X-Toggly-Integration-Id: Integration id (for logging/lookup)

Verify by recomputing with your secret and comparing in constant time. Example (Node.js):

import crypto from 'crypto';

function isValid(req, secret) {
  const signature = req.headers['x-toggly-signature']?.toString().replace('v1=', '');
  const timestamp = req.headers['x-toggly-timestamp'];
  if (!signature || !timestamp) return false;

  const payload = `${timestamp}.${req.bodyRaw}`; // raw body string
  const hmac = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(signature));
}

Testing​

  • Use Webhook.site to capture and inspect requests quickly.
  • Confirm headers, payload shape, and signature; replay against your local endpoint.
  • In Toggly, click “Send Test Webhook” to trigger a sample event.

Troubleshooting​

  • 4xx/5xx responses are counted as errors; see Webhook metrics in Toggly.
  • Ensure your endpoint accepts application/json and reads the raw body for signature verification.
  • If rotating secrets, update your receiver and re-test immediately.