LandfallDocs
Integrations · Telemetry

Connecting Datadog to Landfall

Datadog plugs into Landfall in two independent directions, and you can do either one first:

  • As a source — Beacon, Landfall's diagnosis agent, queries your Datadog metrics and logs while it works an incident. Two keys and your site.
  • As a trigger — a Datadog monitor opens a Landfall incident the moment it alerts. One webhook.

They are worth doing together. A monitor that opens an incident but no source connection gives the agent an alert it cannot investigate; a source connection with no trigger means somebody still has to notice the alert and open the room by hand.

Datadog
monitor alerts
→
Landfall
incident opens
→
Datadog
agent queries back

What you'll need

  • Your Datadog site. It is fixed when the account is created and cannot be changed afterwards — it is shown in Datadog's URL bar and under Organization Settings.
  • Enough access in Datadog to create keys, and to add a webhook and a monitor.
  • An admin on your Landfall organization.

1. Datadog as a source

Landfall only ever reads from Datadog: metric timeseries and log searches, while an incident is being investigated. There is no code path through which it writes to, mutes, or deletes anything in your Datadog account.

Two different kinds of key, and you need both

Datadog has an API key (identifies your organization) and an application key (identifies a user, and is what actually authorizes reads). They look similar and are not interchangeable. The API key alone passes Landfall's connection test and then every metric and log query fails — the integration shows Configured while the agent gets nothing back.

  1. Organization Settings → API Keys

    Click New Key and name it something you'll recognise later, e.g. landfall. Copy the value — the list only ever shows the last four characters again.

    app.datadoghq.com/organization-settings/api-keys
    Datadog's API Keys page listing existing keys with their key id, masked value, creation date and last-used time.

  2. Organization Settings → Application Keys

    Create one here too and copy its value. Application keys belong to the user who created them, so if that account is deactivated the key stops working and Landfall's connection goes unhealthy. For anything long-lived, create it under a service account rather than a person.

    app.datadoghq.com/organization-settings/application-keys
    Datadog's Application Keys page. Each key lists its name, key id, masked value and owning user — the owner is what makes a personal key fragile.

  3. Paste both into Landfall

    Open Settings → Integrations → Datadog for your organization, fill in the fields below, then Test connection and Save. A successful test reads "Datadog API key valid (<your-site>)".

    FieldValue
    API keySent as DD-API-KEY. Required.
    Application keySent as DD-APPLICATION-KEY. Optional to save, required for the agent to read anything.
    Sitedatadoghq.com · datadoghq.eu · us3.datadoghq.com · us5.datadoghq.com · ap1.datadoghq.com · ddog-gov.com
    API base overrideLeave blank. It exists only to point a test environment at a Datadog-compatible endpoint.
Test connection failed?
  • Check the site first. A key from a .eu account validated against datadoghq.com is rejected as invalid, which reads like a bad key but isn't. This is the most common cause.
  • Confirm the key hasn't been revoked or rotated since you copied it.
  • Make sure the API key went in the API key field, not the application key field.

2. Datadog as a trigger

A Datadog webhook posts to Landfall's ingest endpoint, authenticated by a per-organization bearer token. The token is what selects your organization, so the URL carries no organization name and cannot be used to guess one.

  1. Mint a trigger ingest token in Landfall

    An owner or admin issues it from your organization's settings. The raw value is shown once — re-issuing replaces the old one immediately, which is also how you revoke it.

  2. Datadog → Integrations → Webhooks → New

    Namelandfall
    URLhttps://api.landfalls.ai/triggers
    Custom headers{ "Authorization": "Bearer <your ingest token>", "Content-Type": "application/json" }
    Encode as formLeave unchecked — Landfall expects a JSON body

    Paste this into the Payload field:

    {
  "title": "$ALERT_TITLE",
  "alert_type": "$ALERT_TYPE",
  "priority": "$ALERT_PRIORITY",
  "body": "$EVENT_MSG",
  "tags": ["service:$TAGS[service]", "env:$TAGS[env]"],
  "link": "$LINK"
}
    Why the tags line looks like that

    The obvious version — "tags": "$TAGS" — does not work, and it fails quietly. Datadog renders $TAGS as a comma-separated string, not a JSON array, and Landfall only reads tags when it is genuinely an array. Your incident still opens, with no service attached to it. The per-key form $TAGS[service] pulls one tag's value; wrapping it in a literal array gives Landfall the shape it reads. A monitor with no service tag renders empty and is skipped, which is harmless.

  3. Point a monitor at it

    Add @webhook-landfall to the monitor's notification message. Everything else is an ordinary monitor. When it alerts, Datadog records the delivery under Notifications, which is the first place to look if no incident appears.

    app.datadoghq.com/monitors/…
    A Datadog log monitor in the ALERT state. The right-hand panel shows Status: Alert and 'Notifications: 1 sent to 1 recipient(s)', and the message template below ends with @webhook-landfall.
    "1 sent to 1 recipient(s)" is the webhook firing. If that says 0, the monitor never reached Landfall and the problem is in Datadog, not here.

What Datadog's fields become

Template fieldBecomes
titleThe incident title. Defaults to "Datadog alert" if absent.
prioritySeverity, and it wins over alert_type: P1→sev1, P2→sev2, P3→sev3, P4/P5→sev4.
alert_typeSeverity when no priority is set: error → sev2, warning → sev3.
bodyThe summary on the incident's first timeline event.
tagsEntity context. A service:<name> entry resolves the incident to that service.

Landfall recognises a body as Datadog's when it carries an alert_type string or a tags array, so keep at least alert_type even if you drop everything else.

What it looks like when both are connected

The monitor alerts, the incident opens on its own, and Beacon starts working — querying back into the same telemetry the alert came from.

app.landfalls.ai · war room
A Landfall war room opened by a Datadog monitor. The canvas shows an investigation-status widget and a two-track remediation widget; the right-hand feed shows the agent querying telemetry live.
An incident opened by the Datadog webhook, with the agent already investigating.
Seeing "denied" lines in the agent's activity?

That is the two halves being out of step: the trigger is connected but the source is not. The agent receives a Datadog-shaped alert, tries to query the Datadog resource it names, and is refused because your organization has no Datadog connection saved. Finish section 1 and the same incident becomes investigable.

What Landfall does with the connection

  • Reads only. Metric timeseries and log searches. Nothing in Landfall writes to, mutes, or deletes anything in Datadog.
  • Per organization. Your keys belong to your Landfall organization alone and are resolved per request — never shared, never a platform-wide credential.
  • Revocable from your side. Delete either key in Datadog, or re-issue the ingest token in Landfall, and access ends immediately with no coordination needed.