Datadog¶

Datadog alerts reach the platform through Halo's stock Datadog integration, which posts a webhook payload to your instance and opens a ticket. The vendor's setup gets alerts in the door. This page covers what we change on top of it, so an incoming alert lands as a properly typed, categorized Alert ticket that carries its technical detail and maps to your compliance framework automatically.

Start with the vendor guide¶

Halo documents the base integration end to end. Follow it first, then apply the refinements below to the webhook payload.

Datadog Integration (Halo guide 2283)

Its setup, in brief:

1. Enable the Datadog module under Configuration > Integrations.
2. Enter your Datadog Site URL and API Key, plus an Application Key if you are forwarding security signals.
3. Create an API application in the platform (Client ID and Secret, Login Type: Agent) for Datadog to authenticate against.
4. In Datadog, add an Auth Method using OAuth 2.0 client credentials pointed at your token endpoint.
5. Create the webhook, pointed at https://<your instance>/api/notify/datadog.
6. Notify the webhook from a monitor or detection rule with @webhook-<name>.

Everything from here changes only the webhook payload and how many webhooks you create.

Why the payload matters¶

The stock payload opens a ticket with a summary, a priority, and a link back to Datadog. That is enough to notice an alert, and not enough to work one. Three things follow from the payload in GRC-ITSM:

Target the Alert ticket type¶

Set the ticket type explicitly in the payload rather than relying on the integration's Default Ticket Type:

"tickettype_id": "21"

21 is the Alert ticket type. Confirm the value in your own instance under Configuration > Ticket Types -- the ID appears in the URL when you open the type.

Alerts are the entry point for anything a monitoring or detection tool reports. After triage an alert is either resolved as benign or escalated in place to an Incident. See Alert for the workflow, and the Incident Response playbook for what happens after escalation.

Set the category¶

Category is the field that earns the most from this integration, because framework linkage derives from it. An uncategorized alert is a ticket nobody can trace to a control.

Add the full category path to the payload:

"category_1": "Alerts and Incidents>Security>Suspicious Activity"

Use the path exactly as written, with > separators and no spaces around them. The Alert ticket type accepts these categories:

Security¶

Availability¶

Performance¶

Alerts and Incidents on its own is valid when no child fits, but prefer the most specific category that applies -- the more precise the category, the more precise the derived control linkage.

Set the SLA and priority¶

Alerts run on the Incident SLA, which tracks both a response and a resolution clock. Priority levels in the platform are scoped to their SLA, so a priority level only means what you intend when the SLA is set alongside it. Send both:

"sla_id": "3",
"priority_id": "2"

The Incident SLA's levels:

Choose the level deliberately, because the clock starts the moment the ticket opens. An automated alert firing overnight at Critical carries a 30-minute response target, so reserve level 1 for conditions that genuinely warrant waking someone. Confirm the SLA and priority IDs in your own instance under Configuration > Service Level Agreements.

Map the Alert custom fields¶

Reference custom fields by name rather than by the numeric id the vendor guide uses. Field IDs differ between instances, so a payload built on IDs breaks the moment it is reused; names are stable:

"customfields": [
  { "name": "CFDetectionSource", "value": "Datadog" }
]

The Alert ticket type carries these fields:

Field names are case-sensitive and must be sent exactly as shown, including CFrootcauses, whose lowercase spelling is deliberate and differs from the pattern the other fields follow.

The framework fields on the ticket (FedRAMP Controls, FedRAMP Requirements, FedRAMP KSIs, FedRAMP Rules, CMMC Controls, CMMC Requirements) are never set in the payload. They derive from the category.

Which Datadog variables are worth mapping¶

Datadog's webhook variables are fixed -- you cannot traverse into an object or transform a value in the payload. These are the ones that carry something a responder wants:

Three fields have no usable source and belong to triage:

• External Indicators. Client IPs live inside $SECURITY_SIGNAL_ATTRIBUTES, which returns an object such as {"network":{"client":{"ip":"1.2.3.4"}}, "service": ["agent"]}. There is no scalar variable for the IP alone, and no way to reach into the object from the payload.
• Related CVEs. No webhook variable carries one.
• MITRE fields. Covered below.

MITRE fields¶

Datadog detection rules carry MITRE ATT&CK metadata as rule tags in the form tactic:TA0001-Initial-Access and technique:T1566-Phishing, and those tags are what place a rule on Datadog's ATT&CK map. No webhook variable exposes them, so they cannot travel with the alert.

Fill all three during triage. The responder has the signal in front of them and can read the rule's tags directly, which beats any value baked into a webhook -- a payload's value would be wrong for every rule that does not happen to share it.

MITRE Tactics is a lookup field, so its value must match one of your instance's options exactly. Check the current options under Configuration > Custom Objects > Custom Fields. The platform's options correspond to the MITRE ATT&CK enterprise tactics, so a rule's tag translates directly:

MITRE Techniques and MITRE Subtechniques are free-form, so a responder can paste the rule's technique tag, such as T1566-Phishing, as written.

The payload¶

Monitor alerts¶

For availability and performance monitors:

{
  "datadog_id": "$ID",
  "tickettype_id": "21",
  "category_1": "Alerts and Incidents>Availability>System Outage",
  "summary": "$EVENT_TITLE",
  "details": "$TEXT_ONLY_MSG",
  "sla_id": "3",
  "priority_id": "2",
  "customfields": [
    { "name": "CFDetectionSource", "value": "Datadog" },
    { "name": "CFInternalIndicators", "value": "Host: $HOSTNAME | Scope: $ALERT_SCOPE" },
    { "name": "CFExternalIndicators", "value": "" },
    { "name": "CFRelatedCVEs", "value": "" },
    { "name": "CFMITRETactics", "value": "" },
    { "name": "CFMITRETechniques", "value": "" },
    { "name": "CFMITRESubtechniques", "value": "" }
  ],
  "new_external_link": {
    "table_id": "1",
    "module_id": "391",
    "third_party_id": "$ID",
    "third_party_url": "$LINK",
    "third_party_desc": "$EVENT_TITLE"
  }
}

Security signals¶

For Cloud SIEM detection rules, which carry signal context the monitor payload does not:

{
  "datadog_id": "$ID",
  "security_signal_id": "$SECURITY_SIGNAL_ID",
  "tickettype_id": "21",
  "category_1": "Alerts and Incidents>Security>Suspicious Activity",
  "summary": "$EVENT_TITLE",
  "details": "$EVENT_MSG",
  "sla_id": "3",
  "priority_id": "2",
  "customfields": [
    { "name": "CFDetectionSource", "value": "Datadog Cloud SIEM: $SECURITY_RULE_NAME ($SECURITY_RULE_TYPE)" },
    { "name": "CFInternalIndicators", "value": "Host: $HOSTNAME | Scope: $ALERT_SCOPE" },
    { "name": "CFExternalIndicators", "value": "" },
    { "name": "CFRelatedCVEs", "value": "" },
    { "name": "CFMITRETactics", "value": "" },
    { "name": "CFMITRETechniques", "value": "" },
    { "name": "CFMITRESubtechniques", "value": "" }
  ],
  "new_external_link": {
    "table_id": "1",
    "module_id": "391",
    "third_party_id": "$ID",
    "third_party_url": "$LINK",
    "third_party_desc": "$SECURITY_SIGNAL_ID"
  }
}

The empty fields are deliberate. They are carried in the payload as placeholders so the full Alert field set is visible in one place, and so anyone extending the webhook can see what is available without cross-referencing this page. Fill in any your own instance can supply -- a monitor that always covers one service might reasonably carry a static value another would not -- and delete the lines you do not want set. Confirm field names and lookup options against your instance under Configuration > Custom Objects > Custom Fields before relying on them.

Fire one test alert into a non-production instance before going live. MITRE Tactics is a lookup field, and how a given instance treats an empty value on a lookup is worth confirming rather than assuming -- if the blank placeholder is rejected, drop that line and set the field during triage instead.

Keep the vendor guide's datadog_id, security_signal_id, and new_external_link values as it defines them. The identifiers tie the ticket to the originating alert, and the external link is what lets a responder reach the Datadog graph or signal in one click.

Control which events open tickets¶

By default a webhook fires on every state change a monitor goes through, so a single flapping monitor can open a ticket on trigger, another on renotify, and another on recovery. $ALERT_TRANSITION identifies which is which, returning values including Triggered, Re-Triggered, Recovered, Renotify, Warn, and No Data.

Two ways to keep the queue clean:

• Notify the webhook only on the transitions you want. A handle placed outside a conditional block fires on every state transition; one placed inside fires only when that condition matches. Wrapping the mention in the alert condition keeps recoveries from ever reaching the platform:

  {{#is_alert}}@webhook-Halo-Alert-Availability-System-Outage{{/is_alert}}
  

  A webhook scoped this way still fires on renotification, since a renotify re-sends the alert message. - Include $ALERT_TRANSITION in the ticket details where you do forward multiple transitions, so a responder can see at a glance whether they are looking at a new condition or a repeat.

$ALERT_CYCLE_KEY stays constant from the moment an alert triggers until it resolves, which makes it the right identifier if you later automate matching follow-up events to an existing ticket rather than opening a new one.

Field reference¶

Datadog allows each webhook request 15 seconds and retries up to five times on a 5XX response or an internal error, so a brief platform outage will not lose an alert outright.

Assets¶

The Alert ticket type carries the Asset field, but Datadog identifies a host by name and the platform links assets by record. Send $HOSTNAME into Internal Indicators as shown above, and link the asset during triage so the alert joins that asset's history. Where a monitor's hosts map predictably to inventory records, a ticket rule can match the hostname and set the asset automatically.

Verify the setup¶

1. In Datadog, open the webhook and use Test Notifications to fire a sample monitor alert. Detection rules cannot be tested this way and require a real signal.
2. Confirm the ticket opens as an Alert, not the integration's default type.
3. Confirm the category is set and the framework fields populated from it.
4. Confirm Detection Source and Internal Indicators carry values, and the Datadog link resolves.
5. Run one alert all the way through triage, including escalation to an Incident, before pointing production monitors at the webhook.