{"_id":"5d791c1fb5ec88001e1ce8d3","project":"564e5930c3553e0d003e53d0","version":{"_id":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","__v":27,"createdAt":"2015-11-19T23:26:19.166Z","releaseDate":"2015-11-19T23:26:19.166Z","categories":["564e5a9b1560880d008d30dd","566318e1f5ca460d00f41896","56631d08cd54d50d005015fa","56631d2a81ad7417006a202c","5668ba19fbd7680d009375f4","5668cb8b10bda80d00797ed9","5668cb9d10bda80d00797eda","56830d8a3f94e00d004e2a7a","56830d9072bb720d0091f594","56830d94cb4d190d0027698e","56830dc44aecbd0d00a464c5","569e90f3c9b43e0d00c4bab1","56a96d338791090d00113bab","56b12d8336d2580d00247877","56c36bf0a869d017002ea55b","56c36bf93d30210d00ea84bb","56c77749b935671700ff0304","56c7ab9e5652c217008e091a","56cb8bdad5c6241d00ef5e61","58aefce02470660f00b54539","58aefd0bebd7370f0078b954","59ca65ca4337830026edf24f","5c33cd9eb47ba20051ac8d64","5c33df728bec1d0063431c34","5c4783ef523219027055513a","5c4f35033400f3010203a999","5d1d0c9f19c3a0003aeb525a"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Foundation","version_clean":"2.0.0","version":"2"},"category":{"_id":"5d1d0c9f19c3a0003aeb525a","project":"564e5930c3553e0d003e53d0","version":"564e5a9b1560880d008d30dc","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2019-07-03T20:14:23.802Z","from_sync":false,"order":2,"slug":"app-integration-development","title":"App / Integration Development"},"user":"59e10aa4bf9ac7001a235dd6","__v":0,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2019-09-11T16:09:03.895Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"## What is Events Integration functionality?\nEvents Integration allows you to send machine events **from** your tool **to** PagerDuty over our asynchronous [Events API v2](doc:events-api-v2). \n\n## Why should I use Events Integration?\nThis is the best way for monitoring tools to connect with PagerDuty in order to trigger incidents. You'll also be able to acknowledge and resolve incidents. Using the Events API means your app will work with PagerDuty's [Event Intelligence](https://www.pagerduty.com/platform/event-intelligence-and-automation/) features like intelligent grouping and triage.\n\n## Add Events Integration to your app\n\n1. First [create an app in PagerDuty](https://v2.developer.pagerduty.com/docs/how-to-build-an-app)\n\n2. In the **Functionality** section, click **Add** next to Events Integration. Then click **Save** on the Events Integration config page.\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/3c576a1-events_integration.png\",\n        \"events_integration.png\",\n        1316,\n        636,\n        \"#d6d7d9\"\n      ]\n    }\n  ]\n}\n[/block]\n\n## Simple Install Flow (optional, but recommended)\n\nThe Simple Install Flow provides an interface for installing a PagerDuty integration directly from your application. Similar to OAuth!\n\n**Why should I use this flow?**\n* Better experience for users. They don't need to copy and paste keys from PagerDuty.\n* Less work for you (interface is built and maintained by PagerDuty)\n\n**See it in action here:** [acme.pagerduty.dev](https://acme.pagerduty.dev)\n\nFollow these steps to leverage the simple install flow in your app:\n\n3. Add a redirect URL for your application. This is where we will redirect the browser to once the user completes the install flow. You can optionally include additional query parameters which will be passed through and returned on redirect.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/078f35b-Screen_Shot_2019-09-20_at_1.34.43_PM.png\",\n        \"Screen Shot 2019-09-20 at 1.34.43 PM.png\",\n        1510,\n        564,\n        \"#e2e4e5\"\n      ]\n    }\n  ]\n}\n[/block]\n4. Implement a page in your app which will receive the request. You should be prepared to handle a request in this format. Note: you will receive a collection of integration keys and should be prepared to handle more than one.\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET http://<your app URL>?config=<encoded JSON>\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"`integration_key`\",\n    \"1-0\": \"`name`\",\n    \"2-0\": \"`id`\",\n    \"3-0\": \"`type`\",\n    \"0-1\": \"For use the with PagerDuty Events API\",\n    \"1-1\": \"Name of the object the integration key connects to\",\n    \"2-1\": \"Unique ID of the object the integration key connects to\",\n    \"3-1\": \"Type of object (service, global_event_rules, team_rules) \\nNote: others may be added in the future\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\nDecoded JSON will follow this format:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"integration_keys\\\": [\\n    {\\n      \\\"integration_key\\\": \\\"key1\\\",\\n      \\\"name\\\": \\\"Super Cool Service\\\",\\n      \\\"id\\\": \\\"PD12345\\\",\\n      \\\"type\\\": \\\"service\\\"\\n    },\\n    {\\n      \\\"integration_key\\\": \\\"key2\\\",\\n      \\\"name\\\": \\\"Global Event Rules\\\",\\n      \\\"id\\\": \\\"PD6789A\\\",\\n      \\\"type\\\": \\\"global_rule_set\\\"\\n    },\\n    {\\n      \\\"integration_key\\\": \\\"key3\\\",\\n      \\\"name\\\": \\\"B Team's Rules\\\",\\n      \\\"id\\\": \\\"PDBCDEF\\\",\\n      \\\"type\\\": \\\"team_rule_set\\\"\\n    }\\n  ],\\n  \\\"account\\\": {\\n    \\\"subdomain\\\": \\\"dev-acme\\\",\\n    \\\"Name\\\": \\\"Acme Monitoring\\\"\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n6. Once you’ve saved, test out your flow using the **Integration Setup URL** on the page.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/90292f5-Screen_Shot_2019-09-20_at_1.45.34_PM.png\",\n        \"Screen Shot 2019-09-20 at 1.45.34 PM.png\",\n        1218,\n        172,\n        \"#e0e0e1\"\n      ]\n    }\n  ]\n}\n[/block]\n7. Present this link to users in your application at the right time.\n\n## Test your integration\n\nBefore submitting, make sure your integration is able to trigger, acknowledge, or resolve events in PagerDuty as you expect.\n\n1. Create a test service on the Events Integration page. When you click Create, a schedule and escalation policy will also be created and added to the service.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/b4f87c2-Screen_Shot_2019-09-20_at_1.56.29_PM.png\",\n        \"Screen Shot 2019-09-20 at 1.56.29 PM.png\",\n        1214,\n        240,\n        \"#d8dadc\"\n      ]\n    }\n  ]\n}\n[/block]\n2. Send test events to the integration key for your test service\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/1e2f694-download.png\",\n        \"download.png\",\n        1348,\n        414,\n        \"#e0e1e1\"\n      ]\n    }\n  ]\n}\n[/block]\n3. Click **View** to go to the service page and view incidents or check your notifications to see if they look as you expect.","excerpt":"","slug":"developing-a-pagerduty-integration","type":"basic","title":"Events Integration Functionality"}

Events Integration Functionality


## What is Events Integration functionality? Events Integration allows you to send machine events **from** your tool **to** PagerDuty over our asynchronous [Events API v2](doc:events-api-v2). ## Why should I use Events Integration? This is the best way for monitoring tools to connect with PagerDuty in order to trigger incidents. You'll also be able to acknowledge and resolve incidents. Using the Events API means your app will work with PagerDuty's [Event Intelligence](https://www.pagerduty.com/platform/event-intelligence-and-automation/) features like intelligent grouping and triage. ## Add Events Integration to your app 1. First [create an app in PagerDuty](https://v2.developer.pagerduty.com/docs/how-to-build-an-app) 2. In the **Functionality** section, click **Add** next to Events Integration. Then click **Save** on the Events Integration config page. [block:image] { "images": [ { "image": [ "https://files.readme.io/3c576a1-events_integration.png", "events_integration.png", 1316, 636, "#d6d7d9" ] } ] } [/block] ## Simple Install Flow (optional, but recommended) The Simple Install Flow provides an interface for installing a PagerDuty integration directly from your application. Similar to OAuth! **Why should I use this flow?** * Better experience for users. They don't need to copy and paste keys from PagerDuty. * Less work for you (interface is built and maintained by PagerDuty) **See it in action here:** [acme.pagerduty.dev](https://acme.pagerduty.dev) Follow these steps to leverage the simple install flow in your app: 3. Add a redirect URL for your application. This is where we will redirect the browser to once the user completes the install flow. You can optionally include additional query parameters which will be passed through and returned on redirect. [block:image] { "images": [ { "image": [ "https://files.readme.io/078f35b-Screen_Shot_2019-09-20_at_1.34.43_PM.png", "Screen Shot 2019-09-20 at 1.34.43 PM.png", 1510, 564, "#e2e4e5" ] } ] } [/block] 4. Implement a page in your app which will receive the request. You should be prepared to handle a request in this format. Note: you will receive a collection of integration keys and should be prepared to handle more than one. [block:code] { "codes": [ { "code": "GET http://<your app URL>?config=<encoded JSON>", "language": "http" } ] } [/block] [block:parameters] { "data": { "0-0": "`integration_key`", "1-0": "`name`", "2-0": "`id`", "3-0": "`type`", "0-1": "For use the with PagerDuty Events API", "1-1": "Name of the object the integration key connects to", "2-1": "Unique ID of the object the integration key connects to", "3-1": "Type of object (service, global_event_rules, team_rules) \nNote: others may be added in the future" }, "cols": 2, "rows": 4 } [/block] Decoded JSON will follow this format: [block:code] { "codes": [ { "code": "{\n \"integration_keys\": [\n {\n \"integration_key\": \"key1\",\n \"name\": \"Super Cool Service\",\n \"id\": \"PD12345\",\n \"type\": \"service\"\n },\n {\n \"integration_key\": \"key2\",\n \"name\": \"Global Event Rules\",\n \"id\": \"PD6789A\",\n \"type\": \"global_rule_set\"\n },\n {\n \"integration_key\": \"key3\",\n \"name\": \"B Team's Rules\",\n \"id\": \"PDBCDEF\",\n \"type\": \"team_rule_set\"\n }\n ],\n \"account\": {\n \"subdomain\": \"dev-acme\",\n \"Name\": \"Acme Monitoring\"\n }\n}", "language": "json" } ] } [/block] 6. Once you’ve saved, test out your flow using the **Integration Setup URL** on the page. [block:image] { "images": [ { "image": [ "https://files.readme.io/90292f5-Screen_Shot_2019-09-20_at_1.45.34_PM.png", "Screen Shot 2019-09-20 at 1.45.34 PM.png", 1218, 172, "#e0e0e1" ] } ] } [/block] 7. Present this link to users in your application at the right time. ## Test your integration Before submitting, make sure your integration is able to trigger, acknowledge, or resolve events in PagerDuty as you expect. 1. Create a test service on the Events Integration page. When you click Create, a schedule and escalation policy will also be created and added to the service. [block:image] { "images": [ { "image": [ "https://files.readme.io/b4f87c2-Screen_Shot_2019-09-20_at_1.56.29_PM.png", "Screen Shot 2019-09-20 at 1.56.29 PM.png", 1214, 240, "#d8dadc" ] } ] } [/block] 2. Send test events to the integration key for your test service [block:image] { "images": [ { "image": [ "https://files.readme.io/1e2f694-download.png", "download.png", 1348, 414, "#e0e1e1" ] } ] } [/block] 3. Click **View** to go to the service page and view incidents or check your notifications to see if they look as you expect.