Webhook

Firefly integrates with webhooks to provide real-time notifications for various events and alerts. This integration enables teams to receive updates about infrastructure changes, policy violations, drift detection, and other important events directly to their custom endpoints.

Prerequisites

• A service or application that can receive webhook notifications.

• A valid webhook URL endpoint.

• (Optional) Credentials for the endpoint — either a username and password for HTTP Basic auth, or a custom Authorization header value.

Setup Procedure

1. Go to your service or app and generate an incoming webhook URL.

2. In Firefly, click Settings > Integrations.

3. Click Add New > Webhook Integration.

4. Enter a descriptive name in the Nickname field.

5. Add the Webhook URL.

6. (Optional) Select Add custom credentials and choose an Authorization method — see Authentication.

7. Click Next.

8. Click Done.

Authentication

Webhook integrations can authenticate to your endpoint with one of two mutually exclusive methods. Select Add custom credentials during setup to choose one.

Basic

Enter a Username and Password. Firefly sends them as a standard HTTP Basic Authorization header.

Authorization header

Enter an Authorization header value. Firefly sends it verbatim as the Authorization header — include the scheme; Firefly adds no prefix and no encoding of its own.

Use this method for endpoints that do not accept HTTP Basic auth:

Endpoint expects	Enter
Bearer / OAuth / JWT	Bearer <TOKEN>
API-key style gateways	Api-Key <KEY>
A vendor-specific scheme	<Scheme> <TOKEN>

Only one method is active on an integration — setting an Authorization header value clears any stored username and password, and vice versa.

Credentials are stored encrypted. They are never returned by the Firefly API and never appear in logs.

The webhook URL is sent exactly as entered, including any query string — so an endpoint that authenticates with a URL parameter keeps working unchanged.

Example: an endpoint with a vendor-specific scheme

1. In the receiving service, create the token or API key it expects.

2. In Firefly, add a Webhook Integration whose Webhook URL is the receiving endpoint.

3. Select Add custom credentials and set Authorization method to Authorization header.

4. In Authorization header value, enter the whole header value the service expects — its scheme followed by the token, for example <Scheme> <TOKEN>.

5. Use the notification test button on the integration settings page to confirm delivery.

Updating Credentials

Stored credentials are never displayed. To rotate them:

1. Click Settings > Integrations and edit the webhook integration.

2. Select Replace credentials.

3. Choose the Authorization method and enter the new values.

4. Click Save.

Leave Replace credentials unchecked to keep the stored credentials unchanged — for example when renaming the integration.

Response Schema

The webhook payload follows this JSON schema:

{
  "accountId": string,
  "accountName": string,
  "assetType": string,
  "integrationId": string,
  "integrationIdentifier": string,
  "integrationName": string,
  "notificationType": string, // "Drift"|"UnmanagedResource"|"GhostResource"|"InsightDetected"
  "providerType": string, // "aws"|"gcp"|"azurerm"|""
  "region": string,
  "samples": [
    {
      "ARN": string,
      "FRN": string,
      "crawlerId": string,
      "drifts": [ // only present if notificationType == "Drift"
        {
          "iacType": string, // "terraform"|"cloudformation"|...
          "iacValue": string,
          "keyName": string,
          "providerValue": string
        }
      ],
      "firstSeen": string, // 1999-01-31T23:59:59.999999999Z format
      "inventoryUpdateTime": string, // 1999-01-31T23:59:59.999999999Z format
      "isChild": bool,
      "isCrawlerEventDriven": bool,
      "isExcluded": bool,
      "isLocked": bool,
      "lastResourceStateChange": string, // 1999-01-31T23:59:59.999999999Z format
      "name": string,
      "ownerData": {
        "ActionType": string,
        "eventName": string,
        "eventTime": string, // 1999-01-31T23:59:59.999999999Z format
        "otherOwnerData": null,
        "userIdentity": {
          "displayName": string,
          "initials": string,
          "type": string
        },
        "workflowId": string
      }
    }
  ],
  "workflowId": string
}

Features Enabled

• Real-time Notifications: Receive immediate alerts for important events.

• Custom Integration: Integrate with any service that supports webhooks.

• Flexible Authentication: HTTP Basic auth or a custom Authorization header.

• Rich Payload: Detailed event information in JSON format.

• Multiple Event Types: Support for various notification types including drift detection and resource management.

Troubleshooting

Firefly tests the endpoint before creating the integration. If the test fails the integration is not created and the wizard reports an invalid webhook URL — check the credential value as well as the URL.

If your endpoint rejects Firefly's credentials on delivery, the integration reports:

Endpoint response	Firefly reports
401 Unauthorized	Invalid credentials
403 Forbidden	Missing write permission for this integration

Note: In the integration settings page, use the notifcation test button to test the integration.