Trigger PagerDuty incidents from Courier

Prerequisites

A PagerDuty account with elevated privileges
A PagerDuty Service with an Events API v2 integration

Setup

Configure PagerDuty integration

Open your Service integrations

In your PagerDuty account, open the Service and its “Integrations” settings.

Add an Events API v2 integration

Add a new “Events API v2” integration and configure it.

Copy the Integration Key

Copy the Integration Key PagerDuty shows for the new integration.

Configure the integration in Courier

Open the in Courier and fill in the fields below, including the Integration Key.


Routing Key	Paste the Integration Key obtained from PagerDuty.
Event Action	The event action, such as trigger.
Source	The host name or fully qualified domain name (FQDN) of the sender.
Severity	The severity level: info, warning, error, or critical.

Profile requirements

PagerDuty needs no recipient profile fields. Courier triggers the incident against the Service behind the integration’s Events API v2 routing key. To route one recipient elsewhere, set pagerduty.routing_key on their profile. It takes precedence over the key on the integration.

const profile = await client.profiles.create('user_123', {
  profile: {
    pagerduty: {
      routing_key: 'PROFILE_SPECIFIC_ROUTING_KEY',
    },
  },
});

profile = client.profiles.create(
    user_id="user_123",
    profile={
        "pagerduty": {
            "routing_key": "PROFILE_SPECIFIC_ROUTING_KEY",
        },
    },
)

curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "pagerduty": {
        "routing_key": "PROFILE_SPECIFIC_ROUTING_KEY"
      }
    }
  }'

profile = courier.profiles.create(
  "user_123",
  profile: {
    pagerduty: {
      routing_key: "PROFILE_SPECIFIC_ROUTING_KEY"
    }
  }
)

profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"pagerduty": map[string]any{
				"routing_key": "PROFILE_SPECIFIC_ROUTING_KEY",
			},
		},
	},
)

ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("pagerduty", JsonValue.from(java.util.Map.of(
            "routing_key", "PROFILE_SPECIFIC_ROUTING_KEY")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);

$profile = $client->profiles->create('user_123', profile: [
  'pagerduty' => [
    'routing_key' => 'PROFILE_SPECIFIC_ROUTING_KEY',
  ],
]);

ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """
        {
          "pagerduty": {
            "routing_key": "PROFILE_SPECIFIC_ROUTING_KEY"
          }
        }
        """
    ),
};
var profile = await client.Profiles.Create(parameters);

courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"pagerduty":{"routing_key":"PROFILE_SPECIFIC_ROUTING_KEY"}}'

With Courier MCP, save the PagerDuty routing key PROFILE_SPECIFIC_ROUTING_KEY on user_123.

Overrides

covers the two levels and which one wins. A provider override changes the payload Courier sends to PagerDuty’s Events API, such as the severity and the source.

const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      user_id: "1234567890",
    },
    providers: {
      pagerduty: {
        override: {
          body: {
            payload: {
              severity: "error",
              source: "a different source",
            },
          },
        },
      },
    },
  },
});

response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "user_id": "1234567890",
        },
        "providers": {
            "pagerduty": {
                "override": {
                    "body": {
                        "payload": {
                            "severity": "error",
                            "source": "a different source",
                        },
                    },
                },
            },
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "user_id": "1234567890"
      },
      "providers": {
        "pagerduty": {
          "override": {
            "body": {
              "payload": {
                "severity": "error",
                "source": "a different source"
              }
            }
          }
        }
      }
    }
  }'

response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      user_id: "1234567890"
    },
    providers: {
      pagerduty: {
        override: {
          body: {
            payload: {
              severity: "error",
              source: "a different source"
            }
          }
        }
      }
    }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("1234567890"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"pagerduty": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"payload": map[string]any{
							"severity": "error",
							"source": "a different source",
						},
					},
				},
			},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("1234567890").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("pagerduty", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "payload", java.util.Map.of(
                            "severity", "error",
                            "source", "a different source"
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'user_id' => '1234567890',
    ],
    'providers' => [
      'pagerduty' => [
        'override' => [
          'body' => [
            'payload' => [
              'severity' => 'error',
              'source' => 'a different source',
            ],
          ],
        ],
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "1234567890" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "pagerduty",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "payload": {
                              "severity": "error",
                              "source": "a different source"
                            }
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "1234567890"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"pagerduty": {"override": {"body": {"payload": {"severity": "error", "source": "a different source"}}}}}'

With Courier MCP, send my template to PagerDuty with the severity and source overridden.

For all supported payload overrides, see the PagerDuty Events API v2 documentation.

Provider details

pagerduty

Courier recommends routing to the channel. Naming this key in routing.channels instead is supported, and sends through just this provider.

Send to a specific provider

When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

Get started

Available integrations

Trigger PagerDuty incidents from Courier

Prerequisites

Setup

Configure PagerDuty integration

Profile requirements

Overrides

Provider details

Send to a specific provider

​Prerequisites

​Setup

​Configure PagerDuty integration

​Profile requirements

​Overrides

​Provider details

Send to a specific provider

Prerequisites

Setup

Configure PagerDuty integration

Profile requirements

Overrides

Provider details