Webhook

Overview

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) Custom credentials for authentication

Setup Procedure

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

2. In Firefly, select Settings > Integrations

3. Select Add New > Webhook Integration

4. Enter a descriptive name in the Nickname field

5. Add the Webhook URL

6. (Optional) Add custom credentials

7. Select Next

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: Support for custom credentials

• Rich Payload: Detailed event information in JSON format

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

Best Practices

• Use HTTPS endpoints for secure communication

• Implement proper authentication mechanisms

• Set up proper error handling and retry mechanisms

• Monitor webhook delivery and response times

• Regularly review and update webhook configurations

Troubleshooting

1. For webhook delivery issues:

   • Verify the webhook URL is valid and accessible

   • Check authentication credentials if configured

   • Monitor response status codes

   • Review webhook logs for errors

2. For payload issues:

   • Validate the JSON schema

   • Check for required fields

   • Verify date formats

   • Ensure proper handling of optional fields

3. For integration issues:

   • Test the webhook endpoint independently

   • Verify network connectivity

   • Check firewall rules

   • Review rate limiting settings