📡 Webhooks via Integrations

ButterflyMX offers webhook support through two integration scopes:

• Building Integrations — configured by administrators for the entire building
• Tenant Integrations — configured by individual tenants for their personal units

Both allow third-party systems to receive real-time notifications for events such as door releases and video calls.

🧭 Integration Scopes: What’s the Difference?

🔔 Supported Events

You can subscribe to the following resource types and actions:

🔗 Webhooks for SDK Integration

Webhooks for the call resource type are essential for partners integrating with the ButterflyMX SDK. These webhooks notify your application when a video call is initiated, allowing you to:

• Trigger custom UI workflows
• Initiate media streams using the SDK
• Log or analyze call activity in real time

📘

Note: The SDK does not initiate connections by itself. You must use webhooks to receive incoming call events and handle them appropriately through your client-side integration. Refer to the ButterflyMX SDK documentation on GitHub for more details.

🏢 Building Integration Setup

Endpoint

POST /v4/buildings/{building_id}/integrations

Sample Request

{
  "data": {
    "type": "integrations",
    "attributes": {
      "integrator": "webhook",
      "configuration": {
        "url": "https://your-webhook-url.com/building-events",
        "method": "post"
      },
      "bindings": [
        {
          "resource_type": "access_log",
          "actions": ["create"]
        },
        {
          "resource_type": "call",
          "actions": ["create"]
        }
      ]
    }
  }
}

👤 Tenant Integration Setup

Endpoint

POST /v4/tenants/{tenant_id}/integrations

✅

Only events associated with the tenant’s own unit or access tools will trigger these webhooks.

Sample Request

{
  "data": {
    "type": "integrations",
    "attributes": {
      "integrator": "webhook",
      "configuration": {
        "url": "https://your-webhook-url.com/tenant-events",
        "method": "post"
      },
      "bindings": [
        {
          "resource_type": "call",
          "actions": ["create"]
        }
      ]
    }
  }
}

📦 Webhook Payload Format

The payload structure is consistent across both integration types:

{
  "event": {
    "resource_type": "access_log",
    "action": "create",
    "data": {
      "id": 123456789,
      "logged_at": "2025-04-24T10:24:35Z",
      "access_point": 22177636,
      "entry_method": "Swipe to open",
      "release_status": "Unlocked",
      "name": "John Tenant",
      "image_url": "https://cdn.butterflymx.com/snapshot.png"
    }
  }
}

🔁 Webhook Management

You can manage integrations with standard CRUD operations:

• List Integrations
  • Building: GET /v4/buildings/{building_id}/integrations
  • Tenant: GET /v4/tenants/{tenant_id}/integrations
• Update Integration
  • PUT /v4/.../integrations/{id}
• Delete Integration
  • DELETE /v4/.../integrations/{id}

✅ Best Practices

• Security: Implement IP filtering or shared secret verification (signatures optional).
• Retry Logic: Respond with 200 OK within 5 seconds to avoid retry.
• Idempotency: Your system should safely handle duplicate deliveries.
• Monitoring: Log and alert on failed deliveries for proactive resolution.

🧪 Testing Tools

• https://webhook.site for real-time inspection