Back to Blogs

Announcing the v2 Alert Data Forwarder Schema

Posted on July 12, 2023


Carbon Black Cloud’s latest-generation Alerts data is available to ingest directly into your Data Forwarder-enabled integrations. Making the full power of Carbon Black Cloud’s updated Alert data available to system integrators, the Data Forwarder for Alerts 2.0.0 Schema provides a continuous stream of rich Carbon Black Cloud Alerts to be integrated into your SIEM, security lake and other custom applications.

Note: This blog was updated on 10th Oct 2023 with additional information.

What’s new about the data emitted in the v2.0.0 Alert Forwarder Schema?

The v2.0.0 Data Forwarder Schema for Alerts (aka “v2 Alert Forwarder Schema”) implements a significantly updated schema, including many breaking changes in the forwarded data as compared to the v1.0.0 Alert Forwarder schema.

Note the the v2 Data Forwarder Config API remains backward compatible and adds support for version_constraint. version_constraint is not supported on the deprecated v1 Data Forwarder Config API. The v1 API’s decommissioning schedule will be announced shortly on the Developer Network blog and Newsletter.

This new Alert Forwarder schema mirrors the v7 Alerts API Schema by design, to make switching between API and Forwarder as painless as possible for developers and users of their integrations.

The only notable difference in schema fields (i.e. fields returned in alert records by the two services) is that Data Forwarder adds a version field (currently = 2.0.0) to all alerts forwarded from the v2 Alert Forwarder.

  • This version field explicitly asserts which version of the Alert Forwarder schema is responsible for generating the forwarded Alert
  • This field is currently the same as what appears in the Schema dropdown on the Add Forwarder and Edit Forwarder pages of the Carbon Black Cloud console
  • In the near future when “semantic versioning” support is fully implemented across the Data Forwarder, the Schema dropdown will be populated from the version_constraint options
  • The full v2 Alert Forwarder schema is documented on the Developer Network - Data Forwarder Schema and API
  • Are you an XDR customer? Good news - the v2.0.0 Alert Forwarder now makes your IDS (Intrusion Detection System) alerts available through the Data Forwarder service as well.

What’s new about configuring an Alert Forwarder?

  • When you create a new Alert Forwarder via API, there is a new, optional request parameter labeled version_constraint, which has two valid choices as of today: 1.0.0 and 2.0.0
    • 1.0.0 represents the original Data Forwarder Alerts Schema (v1)
    • 2.0.0 represents the new Data Forwarder Alerts Schema (v2)
  • If you don’t explicitly set a version_constraint value on POST or PUT API Requests, the Data Forwarder Config API selects the lowest supported value (currently 1.0.0)
    • This ensures the least interruption of service to those who have already built automation against the API and who haven’t yet added support for the version_constraint request parameter
  • When you create a new Alert Forwarder via the UI, you are shown new choice of 1.0.0 or 2.0.0 under the new Schema dropdown
    • The UI defaults to the 2.0.0 schema selection, and you can change that selection to choose 1.0.0
  • Why does the API and the UI behave differently when choosing which Alert Forwarder schema version is the “default”?
    • We assume that UI users (a) see and can change this choice before saving, and (b) generally are creating one-off Alert Forwarder instances that are more likely to intend to use the new Alert Forwarder schema
    • We assume that API users are system integrators who’ve baked automation around the existing API contract and who aren’t closely monitoring API responses for new outcomes that weren’t there when that API version was first released. Quietly forcing their unversioned API request to create an Alert Forwarder that emits schema 2.0.0 that would’ve created an Alert Forwarder that emitted 1.0.0 the day before is not the API contract we intend to create.

How will versioning of this and other Forwarder types be handled in the future?

We are pleased to announce that we are bringing strong versioning controls to the Carbon Black Cloud Data Forwarder in the form of adopting semver (Semantic Versioning). Read more in the Semantic Versioning Support in Carbon Black Cloud Data Forwarder announcement on the Developer Network blog.


Observed Alerts

As part of the Alerts v7 API release and Alert Forwarder Schema v2, Observed Alerts were removed.

  • Observed Alerts will continue to be returned in Alerts v6 API responses and Data Forwarder Alert Schema v1.
  • An Observed Alert can only be enriched by
    • Searching Enriched Events by alert_id
    • Searching Observations by event_id using created_by_event_id from the Observed Alert
  • An Observed Alert is identified by category = MONITORED in the API response and WARNING in the Alert Forwarder output.
  • Observed Alerts are not returned in Alerts v7 API responses or in the Data Forwarder Alert Schema v2.
  • See Announcing the Alerts V7 API and “Observed Alerts” Become “Observations” for more information.

More Information


Have questions or feedback?

  • Feedback about the updates to the Data Forwarder including the Alert 2.0.0 schema and semantic versioning can be provided here. This feedback will be delivered directly to Product Management for review.

For other feedback or functional issues you encounter with the Data Forwarder should be raised through one of the following channels:

  • Subscribe to the Developer Network Newsletter