Skip to main content

Check out Port for yourself 

Trigger Datadog Incident

Overview​

This guide will help you implement a self-service action in Port that allows you to quickly trigger incidents in Datadog directly from Port using Port's self service actions.

You can implement this action in two ways:

  1. GitHub workflow: A more flexible approach that allows for complex workflows and custom logic, suitable for teams that want to maintain their automation in Git.
  2. Synced webhooks: A simpler approach that directly interacts with Datadog's API through Port, ideal for quick implementation and minimal setup.

Prerequisites​

  1. Complete the onboarding process.
  2. Access to your Datadog organization with permissions to create incidents.
  3. Port's GitHub app installed.
  4. Datadog API token with incident_write permission scope.

Set up data model​

If you haven't installed the Datadog integration, you'll need to create a blueprint for Datadog incidents. However we highly recommend you install the Datadog integration to have this automatically set up for you.

Create the Datadog incident blueprint

  1. Go to your Builder page.

  2. Click on + Blueprint.

  3. Click on the {...} button in the top right corner, and choose "Edit JSON".

  4. Add this JSON schema:

    Datadog Incident Blueprint (Click to expand)
    {
      "identifier": "datadogIncident",
      "description": "This blueprint represents a Datadog incident in our software catalog",
      "title": "Datadog Incident",
      "icon": "Datadog",
      "schema": {
        "properties": {
          "customerImpactScope": {
            "title": "Customer Impact Scope", 
            "description": "A summary of the impact customers experienced during the incident.",
            "type": "string"
          },
          "customerImpacted": {
            "title": "Customer Impacted",
            "description": "A flag indicating whether the incident caused customer impact.",
            "type": "boolean",
            "default": false
          },
          "customerImpactStart": {
            "title": "Customer Impact Start",
            "type": "string", 
            "description": "Start time of incident affecting customer",
            "format": "date-time"
          },
          "customerImpactEnd": {
            "title": "Customer Impact End",
            "description": "End timestamp of incident affecting customers",
            "type": "string",
            "format": "date-time"
          },
          "created": {
            "title": "Created At",
            "description": "Timestamp of incident creation",
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "title": "Updated At",
            "description": "Last time incident was updated",
            "type": "string",
            "format": "date-time"
          },
          "customerImpactDuration": {
            "title": "Customer Impact Duration",
            "description": "Duration of customer impact",
            "type": "number"
          },
          "timeToDetect": {
            "title": "Time To Detect",
            "description": "Number of seconds it took to detect incident",
            "type": "number"
          },
          "timeToRepair": {
            "title": "Time To Repair",
            "description": "Number of seconds it took to fix incident",
            "type": "number"
          },
          "severity": {
            "title": "Severity",
            "description": "Severity of incident",
            "type": "string"
          },
          "state": {
            "title": "State",
            "description": "State of the incident",
            "type": "string"
          },
          "createdBy": {
            "title": "Created By",
            "description": "Name of user that created this incident",
            "type": "string"
          }
        }
      },
      "calculationProperties": {},
      "relations": {}
    }

  5. Click "Save" to create the blueprint.

Implementation​

You can trigger Datadog incidents by leveraging Port's synced webhooks and secrets to directly interact with the Datadog's API. This method simplifies the setup by handling everything within Port.

Add Port secrets

Existing secrets

If you have already installed Port's Datadog integration, these secrets should already exist in your portal.
To view your existing secrets:

  1. Click on the ... button in the top right corner of your Port application.
  2. Choose Credentials, then click on the Secrets tab.

To add these secrets to your portal:

  1. Click on the ... button in the top right corner of your Port application.

  2. Click on Credentials.

  3. Click on the Secrets tab.

  4. Click on + Secret and add the following secrets:

    • DD_API_KEY: Your Datadog API Key.
    • DD_APPLICATION_KEY: Your Datadog Application Key.

Set up self-service action

Follow these steps to create the self-service action:

  1. Head to the self-service page.

  2. Click on the + New Action button.

  3. Click on the {...} Edit JSON button.

  4. Copy and paste the following JSON configuration into the editor.

    Trigger Datadog Incident Action Using Synced Webhook (Click to expand)
    Modification Required

    Make sure to replace <YOUR_DD_API_URL> with your Datadog API URL.
    Datadog API URL by default should be https://api.datadoghq.com. However, if you are on the Datadog EU site, set the secret to https://api.datadoghq.eu.
    If you have your region information you use https://api.<region>.datadoghq.com or https://api.<region>.datadoghq.eu.

    {
      "identifier": "datadogIncident_trigger_datadog_incident_webhook",
      "title": "Trigger Datadog Incident (Webhook)",
      "icon": "Datadog",
      "description": "Triggers a Datadog incident using a synced webhook",
      "trigger": {
        "type": "self-service",
        "operation": "CREATE",
        "userInputs": {
          "properties": {
            "title": {
              "title": "Title",
              "description": "The title of the incident, summarizing what happened.",
              "type": "string"
            },
            "customerImpacted": {
              "title": "Customer Impacted",
              "description": "Indicates whether the incident caused customer impact.",
              "type": "boolean",
              "default": false
            },
            "customerImpactScope": {
              "icon": "DefaultProperty",
              "title": "Customer Impact Scope",
              "description": "Summary of the impact experienced by customers.",
              "type": "string"
            },
            "notificationHandleName": {
              "title": "Notification Handle Name",
              "description": "The name of the notification handle.",
              "type": "string"
            },
            "notificationHandleEmail": {
              "title": "Notification Handle Email",
              "description": "The email address used for the notification.",
              "type": "string",
              "pattern": "^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
            }
          },
          "required": [
            "title",
            "customerImpacted",
            "notificationHandleName",
            "notificationHandleEmail",
            "customerImpactScope"
          ],
          "order": [
            "title",
            "customerImpacted",
            "customerImpactScope",
            "notificationHandleName",
            "notificationHandleEmail"
          ]
        },
        "blueprintIdentifier": "datadogIncident"
      },
      "invocationMethod": {
        "type": "WEBHOOK",
        "url": "<YOUR_DD_API_URL>/api/v2/incidents",
        "agent": false,
        "synchronized": true,
        "method": "POST",
        "headers": {
          "Content-Type": "application/json",
          "DD-API-KEY": "{{ .secrets.DD_API_KEY }}",
          "DD-APPLICATION-KEY": "{{ .secrets.DD_APPLICATION_KEY }}"
        },
        "body": {
          "data": {
            "type": "incidents",
            "attributes": {
              "customer_impact_scope": "{{.inputs.\"customerImpactScope\"}}",
              "customer_impacted": "{{.inputs.\"customerImpacted\"}}",
              "title": "{{.inputs.\"title\"}}",
              "notification_handles": [
                {
                  "display_name": "{{.inputs.\"notificationHandleName\"}}",
                  "handle": "{{.inputs.\"notificationHandleEmail\"}}"
                }
              ]
            }
          }
        }
      },
      "requiredApproval": false
    }

  5. Click Save.

Now you should see the Trigger Datadog Incident (Webhook) action in the self-service page. 🎉

Install the Datadog Integration

Triggering the incident data via the api will not automatically update the incident data in your Port catalog.
To ensure that the Datadog incident data remains up to date in your catalog, install the Datadog integration in Port.

Let's test it!​

  1. Head to the self-service page of your portal

  2. Choose either the GitHub workflow or webhook implementation:

    • For GitHub workflow: Click on Trigger Datadog Incident
    • For webhook: Click on Trigger Datadog Incident (Webhook)

  3. Fill in the incident details:

    • Title of the incident
    • Whether customers are impacted
    • Customer impact scope (if customers are impacted)
    • Notification handle name and email

  4. Click on Execute

  5. Wait for:

    • GitHub workflow: The workflow to complete and create the incident
    • Webhook: The incident to be created in Datadog

  6. Check your Datadog incidents page to see the new incident