App Event Webhooks

App event webhooks provide real-time notifications about connector and app-specific delivery events. These events are triggered when data is delivered to external platforms through Narrative's connectors.

Overview

App events differ from job events in that they focus on external connector operations rather than internal platform jobs. They provide detailed delivery statistics and status information for data flowing through Narrative's connector ecosystem.

Available Connector App IDs

When creating app event webhook subscriptions, you specify an app_id to monitor events from a specific connector.

App Event Types

App events follow the pattern: {connector_name}.{event_category}.{event_status}

Event Categories

audience.delivery

• Used by Facebook connector for audience deliveries
• Delivers audience data to Facebook ad accounts

taxonomy.delivery

• Used by Yahoo!, Magnite, and other connectors
• Delivers taxonomy/segment data to partner platforms

Event Statuses

completed - Delivery finished successfully
failed - Delivery encountered an error

Connection vs Profile

Understanding the relationship between connections and profiles is important for interpreting app event data:

• Profile: Configuration template for connector settings (credentials, preferences, etc.)
• Connection: Specific instance of a profile tied to a connector endpoint and connected to a dataset for delivery

Each app event references both the profile used and the specific connection that executed the delivery.

App Event Payloads

Facebook Connector - Audience Delivery

Delivers audience data to Facebook ad accounts with detailed delivery statistics.

Successful Delivery:

{
  "created_at": "2025-01-21T15:16:45.552920Z",
  "data": {
    "ad_account": {
      "id": "act_1234567890123456",
      "name": "Example Media Network"
    },
    "app_name": "Facebook Connector",
    "audience": {
      "id": "120224075818070590",
      "name": "Example Audience"
    },
    "company_id": 123,
    "connection_id": "5b1831e8-7964-4249-a819-608291f3984a",
    "dataset": {
      "display_name": "Example Dataset",
      "id": 12345,
      "name": "example_dataset"
    },
    "profile": {
      "id": "b6952c0b-59d4-47f6-8278-564bb4c2cdb1",
      "name": "Example Profile"
    },
    "stats": {
      "rows": 1815,
      "rows_with_email": 1090,
      "rows_with_maid": 725
    }
  },
  "id": "e606bf00-854c-4acb-bf63-553d8795665f",
  "type": "facebook_connector.audience.delivery.completed"
}

Failed Delivery:

{
  "created_at": "2025-01-21T16:50:56.037915Z",
  "data": {
    "app_name": "Facebook Connector",
    "company_id": 123,
    "connection_id": "5aa9d2c7-4dba-4e70-9ccc-400f66ac7a9c",
    "dataset": {
      "display_name": "Example Segment",
      "id": 12348,
      "name": "example_segment"
    },
    "error_code": "Internal Error",
    "error_details": {
      "ad_account": {
        "id": "act_1234567890123456",
        "name": "Example Media Network"
      },
      "audience": {
        "id": "120224075820680590",
        "name": "Example Segment"
      }
    },
    "error_message": "Audience delivery failed. We apologize for the inconvenience. Our team has been alerted and is investigating the issue. Where possible, we will retry the operation automatically. Your Customer Service representative will reach out if any action is needed.",
    "profile": {
      "id": "b6952c0b-59d4-47f6-8278-564bb4c2cdb1",
      "name": "Example Profile"
    }
  },
  "id": "3196f22a-57c4-4524-aaee-3c7f24d6b492",
  "type": "facebook_connector.audience.delivery.failed"
}

Yahoo! Connector - Taxonomy Delivery

Delivers taxonomy/segment data to Yahoo! platforms.

{
  "created_at": "2025-01-21T15:17:29.444750Z",
  "data": {
    "app_name": "Yahoo! Connector",
    "company_id": 123,
    "connection_id": "d09036dc-6f85-479e-a759-e01b7f0631f3",
    "dataset": {
      "display_name": "Example Category",
      "id": 12346,
      "name": "example_category"
    },
    "profile": {
      "id": "bb85c73e-bf2e-440b-83b0-75c3294d9f32",
      "name": "Example Profile"
    },
    "stats": {
      "rows": 38
    },
    "taxonomy": {
      "id": "3ba391c5-787e-4b07-b0e8-42c44cd63f23",
      "name": "Example Category"
    },
    "urn_type": "IDFA"
  },
  "id": "87806991-deaa-4f4e-8baf-eb680fab64f6",
  "type": "yahoo_connector.taxonomy.delivery.completed"
}

Magnite Connector - Taxonomy Delivery

Delivers taxonomy/segment data to Magnite platforms with detailed identifier breakdowns.

{
  "created_at": "2025-01-21T15:14:46.718096Z",
  "data": {
    "app_name": "Magnite Connector",
    "company_id": 123,
    "connection_id": "144436fe-5440-4350-ae06-ec47851e7dc6",
    "dataset": {
      "display_name": "Example Segment",
      "id": 12347,
      "name": "example_segment"
    },
    "element": {
      "id": "81f15310-bee1-4148-afbd-5717a1e89e96",
      "name": "Example Segment"
    },
    "profile": {
      "id": "9fcb4b47-4c3e-4426-82fe-f21aca9a45b3",
      "name": "Example Profile"
    },
    "stats": {
      "aaids": 0,
      "cookies": 0,
      "ctv_ids": 0,
      "idfas": 0,
      "ips": 0,
      "rows": 0,
      "rows_with_aaid": 0,
      "rows_with_cookie": 0,
      "rows_with_ctv_id": 0,
      "rows_with_idfa": 0,
      "rows_with_ip": 0
    }
  },
  "id": "d059528e-0f91-4324-a21b-4cdaf40b64e5",
  "type": "magnite_connector.taxonomy.delivery.completed"
}

Delivery Statistics

App events include detailed delivery statistics that vary by connector:

Facebook Connector Stats

• rows: Total number of records delivered
• rows_with_email: Records containing email addresses
• rows_with_maid: Records containing mobile advertising IDs

Yahoo! Connector Stats

• rows: Total number of records delivered
• urn_type: Type of identifier used (IDFA, AAID, etc.)

Magnite Connector Stats

• rows: Total number of records delivered
• aaids: Android Advertising IDs count
• cookies: Cookie identifiers count
• ctv_ids: Connected TV identifiers count
• idfas: iOS identifiers count
• ips: IP address count
• rows_with_*: Count of records containing each identifier type

Error Handling

When connector deliveries fail, a failure event is sent with comprehensive error information:

Error Fields

• error_code: High-level error category
• error_message: Detailed error description for users
• error_details: Additional context about the failed delivery (varies by connector)

The error_details object typically includes:

• Target platform information (ad account, audience, etc.)
• Specific identifiers that failed
• Platform-specific error context

Next Steps