{"_id":"56a16a3f470ae00d00c30632","category":{"_id":"5668cb9d10bda80d00797eda","__v":5,"pages":["5668cbaf5d13810d00609621","56830d13cb4d190d00276989","56a16a3f470ae00d00c30632","56db37dfed07490b00c7b29b","56e6fe61cb97fd200068ecc4"],"project":"564e5930c3553e0d003e53d0","version":"564e5a9b1560880d008d30dc","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-12-10T00:47:25.740Z","from_sync":false,"order":5,"slug":"betas","title":"Build"},"__v":9,"parentDoc":null,"project":"564e5930c3553e0d003e53d0","user":"5668c7855d13810d0060961d","version":{"_id":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","__v":21,"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"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"Foundation","version_clean":"2.0.0","version":"2"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-21T23:31:11.388Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"Thank you for your interest in integrating your monitoring tool with PagerDuty! This guide will introduce you to the various ways our partners and customers create new monitoring tool integrations with PagerDuty.\n\n**There are four ways to send incidents to PagerDuty:**\n\n  * **Best:** [PD Connect](https://www.pagerduty.com/docs/guides/pagerduty-connect/) and [Events API](doc:events-api) , a streamlined integration workflow allowing your users to easily integrate their accounts on your service with their PagerDuty accounts.\n  * **Good:** [Events API](doc:events-api) only.\n  * **Good:** [PD Agent](https://www.pagerduty.com/docs/guides/agent-install-guide/). PD Agent includes command-line tools to accept events from your monitoring tool to PagerDuty and a daemon process that handles the sending of these events to PagerDuty. This is generally used for on-premise monitoring tools (such as Nagios and Icinga) that have the ability to use command-line tools.\n  * **Okay:** [Email-based integrations](https://www.pagerduty.com/docs/guides/email-integration-guide/). Note that while we fully support email-based integrations, they lack the security and real-time acknowledgement available with our [Events API](doc:events-api). Most of our customers do not consider email-based integrations to be “real” integrations and will ask for something better.\n\n**If you are integrating a proprietary, in-house monitoring tool with PagerDuty**, we recommending using the [Events API](doc:events-api). You can also use the [PD Agent](https://www.pagerduty.com/docs/guides/agent-install-guide/).\n\n**If your monitoring tool will be used by other companies**, we recommend implementing [PD Connect](https://www.pagerduty.com/docs/guides/pagerduty-connect/) and the [Events API](doc:events-api) to provide a one-click integration for your customers. We also strongly recommend that you write an integration guide (with screenshots) that walks your customers through the process on both your application and PagerDuty. If you do so, we will host your integration guide on our site, add your company to our Partners page, and provide a complementary single-user PagerDuty account for your ongoing integration testing needs.\n\n**If it’s relevant to your application, we strongly recommend creating a bi-directional integration.** We’ve found our customers have come to expect their monitoring and incident management tools to remain in sync. PagerDuty can send incident updates (e.g., acknowledge/resolve) to your application in two different ways:\n\n  * **Best:** [Webhooks](doc:webhooks-overview). PagerDuty can automatically send HTTP callbacks whenever an incident is triggered, acknowledged, unacknowledged (due to timeout), resolved, reassigned, escalated, or delegated. Webhooks are specific to a Service. This is the preferred method for SaaS-based monitoring tools.\n  * **Okay:** Regularly poll the [Incidents API](/v2/page/api-reference#!/Incidents/get_incidents) for details about incidents you’ve sent over. [Webhooks](doc:webhooks-overview) are preferable because the [Incidents API](/v2/page/api-reference#!/Incidents/get_incidents) requires an additional, distinct [API token](doc:authentication#api-token-authentication) and polling isn’t fun for anyone. This may be the only option for those running software behind a corporate firewall.\n\n**If your monitoring tool has the notion of maintenance windows**, you may want to develop an integration with our [Maintenance Windows API](/v2/page/api-reference#!/Maintenance_Windows/get_maintenance_windows) to keep the maintenance windows between your application and PagerDuty in sync. A bi-directional integration will require polling, but a longer interval should work relatively well. Note: this API requires the use of an [API token](doc:authentication#api-token-authentication) (distinct from the \"Service Key\" used by the [Events API](doc:events-api)).\n\n**If your monitoring tool has the notion of notes**, you can also [read](/v2/page/api-reference#!/Incidents/get_incidents_id_notes) and [add](/v2/page/api-reference#!/Incidents/post_incidents_id_notes) notes to incidents. A bi-directional integration will require polling. Note: this API requires the use of an  [API token](doc:authentication#api-token-authentication) (distinct from the \"Service Key\" used by the [Events API](doc:events-api)).\n[block:embed]\n{\n  \"html\": false,\n  \"url\": \"https://pdconnect.wufoo.com/forms/z1ybj8dd0qwq9od/\",\n  \"title\": \"Become a PagerDuty Partner\",\n  \"favicon\": \"https://pdconnect.wufoo.com/favicon.ico\",\n  \"iframe\": true,\n  \"height\": \"800px\"\n}\n[/block]","excerpt":"","slug":"integrating","type":"basic","title":"Integrate With PagerDuty"}

Integrate With PagerDuty


Thank you for your interest in integrating your monitoring tool with PagerDuty! This guide will introduce you to the various ways our partners and customers create new monitoring tool integrations with PagerDuty. **There are four ways to send incidents to PagerDuty:** * **Best:** [PD Connect](https://www.pagerduty.com/docs/guides/pagerduty-connect/) and [Events API](doc:events-api) , a streamlined integration workflow allowing your users to easily integrate their accounts on your service with their PagerDuty accounts. * **Good:** [Events API](doc:events-api) only. * **Good:** [PD Agent](https://www.pagerduty.com/docs/guides/agent-install-guide/). PD Agent includes command-line tools to accept events from your monitoring tool to PagerDuty and a daemon process that handles the sending of these events to PagerDuty. This is generally used for on-premise monitoring tools (such as Nagios and Icinga) that have the ability to use command-line tools. * **Okay:** [Email-based integrations](https://www.pagerduty.com/docs/guides/email-integration-guide/). Note that while we fully support email-based integrations, they lack the security and real-time acknowledgement available with our [Events API](doc:events-api). Most of our customers do not consider email-based integrations to be “real” integrations and will ask for something better. **If you are integrating a proprietary, in-house monitoring tool with PagerDuty**, we recommending using the [Events API](doc:events-api). You can also use the [PD Agent](https://www.pagerduty.com/docs/guides/agent-install-guide/). **If your monitoring tool will be used by other companies**, we recommend implementing [PD Connect](https://www.pagerduty.com/docs/guides/pagerduty-connect/) and the [Events API](doc:events-api) to provide a one-click integration for your customers. We also strongly recommend that you write an integration guide (with screenshots) that walks your customers through the process on both your application and PagerDuty. If you do so, we will host your integration guide on our site, add your company to our Partners page, and provide a complementary single-user PagerDuty account for your ongoing integration testing needs. **If it’s relevant to your application, we strongly recommend creating a bi-directional integration.** We’ve found our customers have come to expect their monitoring and incident management tools to remain in sync. PagerDuty can send incident updates (e.g., acknowledge/resolve) to your application in two different ways: * **Best:** [Webhooks](doc:webhooks-overview). PagerDuty can automatically send HTTP callbacks whenever an incident is triggered, acknowledged, unacknowledged (due to timeout), resolved, reassigned, escalated, or delegated. Webhooks are specific to a Service. This is the preferred method for SaaS-based monitoring tools. * **Okay:** Regularly poll the [Incidents API](/v2/page/api-reference#!/Incidents/get_incidents) for details about incidents you’ve sent over. [Webhooks](doc:webhooks-overview) are preferable because the [Incidents API](/v2/page/api-reference#!/Incidents/get_incidents) requires an additional, distinct [API token](doc:authentication#api-token-authentication) and polling isn’t fun for anyone. This may be the only option for those running software behind a corporate firewall. **If your monitoring tool has the notion of maintenance windows**, you may want to develop an integration with our [Maintenance Windows API](/v2/page/api-reference#!/Maintenance_Windows/get_maintenance_windows) to keep the maintenance windows between your application and PagerDuty in sync. A bi-directional integration will require polling, but a longer interval should work relatively well. Note: this API requires the use of an [API token](doc:authentication#api-token-authentication) (distinct from the "Service Key" used by the [Events API](doc:events-api)). **If your monitoring tool has the notion of notes**, you can also [read](/v2/page/api-reference#!/Incidents/get_incidents_id_notes) and [add](/v2/page/api-reference#!/Incidents/post_incidents_id_notes) notes to incidents. A bi-directional integration will require polling. Note: this API requires the use of an [API token](doc:authentication#api-token-authentication) (distinct from the "Service Key" used by the [Events API](doc:events-api)). [block:embed] { "html": false, "url": "https://pdconnect.wufoo.com/forms/z1ybj8dd0qwq9od/", "title": "Become a PagerDuty Partner", "favicon": "https://pdconnect.wufoo.com/favicon.ico", "iframe": true, "height": "800px" } [/block]