Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PORT-10984 Add “synced webhook + secrets” implementation method to relevant guides #1741

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

PORT-10984 Add “synced webhook + secrets” implementation method to relevant guides #1741

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
162 changes: 150 additions & 12 deletions docs/guides/all/trigger-datadog-incident.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,13 @@ description: Learn how to trigger a Datadog incident in Port, ensuring effective
# Trigger Datadog Incident

This GitHub action allows you to quickly trigger incidents in Datadog directly from Port using Port's self service actions.
You can trigger incidents in Datadog using either the GitHub workflow method or the sync webhook method.

## Prerequisites
1. [Port's GitHub app](https://github.com/apps/getport-io) needs to be installed.
2. Datadog API Key. Head over to your account's [API and application keys page](https://app.datadoghq.com/account/settings) to create a new API key. The API key should have the `incident_write` permission scope.
1. [Port's GitHub app](https://github.com/apps/getport-io) needs to be installed if you are using the GitHub workflow method.
2. Datadog API Key. Head over to your account's [API and application keys page](https://app.datadoghq.com/account/settings) to create a new API key.<br/> The API key should have the `incident_write` permission scope.
3. Datadog Application Key. This key is available on the same page as the Datadog API key.
4. In your GitHub repository, [go to **Settings > Secrets**](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) and add the following secrets:
* `DD_API_URL` - Datadog API URL by default should be [https://api.datadoghq.com](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`.
* `DD_API_KEY` - Datadog API Key.
* `DD_APPLICATION_KEY` - Datadog Application Key.
* `PORT_CLIENT_ID` - Port Client ID [learn more](https://docs.getport.io/build-your-software-catalog/sync-data-to-catalog/api/#get-api-token)
* `PORT_CLIENT_SECRET` - Port Client Secret [learn more](https://docs.getport.io/build-your-software-catalog/sync-data-to-catalog/api/#get-api-token)

5. Create a Datadog incident blueprint in Port using the schema below:
4. Create a Datadog incident blueprint in Port using the schema below:

<details>
<summary><b>Datadog Incident Blueprint</b></summary>
Expand Down Expand Up @@ -109,7 +103,19 @@ This GitHub action allows you to quickly trigger incidents in Datadog directly f
</details>


## GitHub Workflow
## Trigger via GitHub workflow
This method uses a GitHub workflow to trigger Datadog incidents.
The workflow is triggered by a self-service action in Port, which sends the required data to the GitHub workflow.

### Add GitHub secrets
In your GitHub repository, [go to **Settings > Secrets**](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) and add the following secrets:
* `DD_API_URL` - Datadog API URL by default should be [https://api.datadoghq.com](https://api.datadoghq.com). <br/> However, if you are on the Datadog EU site, set the secret to `https://api.datadoghq.eu`. <br/>If you have your region information you use `https://api.<region>.datadoghq.com` or `https://api.<region>.datadoghq.eu`.
* `DD_API_KEY` - Datadog API Key.
* `DD_APPLICATION_KEY` - Datadog Application Key.
* `PORT_CLIENT_ID` - Port Client ID [learn more](https://docs.getport.io/build-your-software-catalog/sync-data-to-catalog/api/#get-api-token)
* `PORT_CLIENT_SECRET` - Port Client Secret [learn more](https://docs.getport.io/build-your-software-catalog/sync-data-to-catalog/api/#get-api-token)

### Workflow
Create the file `trigger-datadog-incident.yml` in the `.github/workflows` folder of your repository and copy the content of the workflow configuration below:

:::tip Dedicated repository
Expand Down Expand Up @@ -247,7 +253,7 @@ jobs:

</details>

## Port Configuration
### Port configuration
On the [self-service](https://app.getport.io/self-serve) page, create the Port action against the `Datadog Incident` blueprint. This will trigger the GitHub workflow.

<details>
Expand Down Expand Up @@ -341,6 +347,138 @@ Make sure to replace `<GITHUB_ORG>` and `<GITHUB_REPO>` with your GitHub organiz
```
</details>


## Alternative trigger via webhook

In addition to triggering Datadog incidents via GitHub Actions,
you can leverage on Port's **synced webhooks** and **secrets** to directly interact with Datadog's API.
This method simplifies the setup by handling everything within Port.



### Add Port secrets
Add the following secrets to your Port account:

1. Click on the `...` button next to the profile icon in the top right conner.
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.

### Port configuration
Create a new self service action that uses a synced webhook to trigger a Datadog incident using the following JSON configuration.

<details>
<summary><b>Trigger Datadog Incident Action Using Synced Webhook (Click to expand)</b></summary>

:::tip 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](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`.
:::

```json showLineNumbers
{
"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,
"publish": true
}
```

</details>

:::note 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](/build-your-software-catalog/sync-data-to-catalog/apm-alerting/datadog/) in Port.
This integration will automatically synchronize incident updates from Datadog to your Port catalog.
:::



## Let's test it

1. Trigger the action from Port's [Self Serve hub](https://app.getport.io/self-serve)
Expand Down