Module pagerduty::integration
[−]
[src]
Integration API
The PagerDuty event integration API is how you would add PagerDuty's advanced alerting functionality to any system that can make an HTTP API call. You can now add phone, SMS and email alerting to your monitoring tools, ticketing systems and custom software.
Description
The API was designed to allow you to easily integrate a monitoring system with a Service in PagerDuty. Monitoring systems generally send out events when problems are detected and when these problems have been resolved (fixed). Some more advanced systems also understand the concept of acknowledgements: problems can be acknowledged by an engineer to signal he or she is working on fixing the issue.
Since monitoring systems emit events, the API is based around accepting events. Incoming events (sent via the API) are routed to a PagerDuty service and processed. They may result in a new incident being created, or an existing incident being acknowledged or resolved.
The same event-based API can also be used to integrate a PagerDuty service with ticketing systems and various other software tools.
API Limits
There is a limit on the number of events that a service can accept at any given time. Depending on the behavior of the incoming traffic and how many incidents are being created at once, we reduce our throttle dynamically.
If each of the events your monitoring system is sending is important, be sure to retry on a 403 response code, preferably with a back off.
Response codes and Retry Logic
Ideally, the API request will succeed and the PagerDuty server will indicate that it successfully received that event. In practice, the request may fail due to various reasons.
The following table shows the possible results of the API request and if you need to retry the API call for that result:
| Result | Description | Retry? |
|---|---|---|
| 200 | OK - The event has been accepted by PagerDuty. See below for details. | No |
| 400 | Bad Request - Check that the JSON is valid. See below for details. | No |
| 403 | Forbidden - Too many API calls at a time. | Yes - retry after some time. |
| 5xx | Internal Server Error - the PagerDuty server experienced an error while processing the event. | Yes - retry after some time. |
| Networking Error | Error while trying to communicate with PagerDuty servers. | Yes - retry after some time. |
Modules
| response |
Response types from the integration API |
Structs
| AcknowledgeEvent |
Acknowledge events cause the referenced incident to enter the acknowledged state. |
| Context |
An informational asset attached to the incident |
| ResolveEvent |
Cause the referenced incident to enter the resolved state. |
| TriggerEvent |
Event to report a new or ongoing problem. |
Enums
| Response |
A Response from the integration API |
Functions
| acknowledge |
Send an AcknowledgeEvent request |
| resolve |
Send a ResolveEvent request |
| trigger |
Send a TriggerEvent request |