Overview

Webhooks are requests made by PagerTree to a user-defined URL, the payload provided represents an incident. Webhooks allow you to extend PagerTree by performing any logic you wish.

Create An Outgoing Webhook

  1. In the left hand navigation menu, next to Integrations, click the ”+” button to open the create integration form. Create Integration Button
  2. Supply the following information
    • Name - A descriptive name
    • Type - The integration type Outgoing Webhook
    • URL - The endpoint URL PagerTree will make requests to
    • Username (optional) - Used for Basic Authentication
    • Password (optional) - Used for Basic Authentication
    • Enable/Disable desired event types
  3. Click Create button. Create Integration Form

Data Structure

Outgoing webhooks will send data in a POST request in JSON format to your configured URL. Each request has the following format:

{
  "type": "<event_type>",
  "data": "<object>"
}

Where event_type is an applicable event and data is an incident

Example Payload

{
    "type": "incident.resolved",
    "data": {
        "additional_data": [],
        "acknowledged": 1529600218,
        "status": "resolved",
        "created": 1529600204,
        "createdAt": "2018-06-21T16:56:44.730Z",
        "ttl": 1561136204,
        "d_team_id": "tem_0000319",
        "sid": "acc_0000068",
        "source_id": "usr_0000214",
        "resolved": 1529600234,
        "subscribers": [],
        "urgency": "medium",
        "updatedAt": "2018-06-21T16:57:14.528Z",
        "workflows": [
            {
                "child_workflows": [
                    {
                        "id": "aw-1-0-usr_0000214",
                        "userid": "usr_0000214",
                        "layer": 1,
                        "repeat": 0,
                        "status": "acknowledged"
                    }
                ],
                "current_repeat": 0,
                "schedule": {
                    "blocks": [
                        {
                            "userid": "usr_0000214",
                            "layer": 1
                        },
                        {
                            "userid": "usr_0000591",
                            "layer": 2
                        }
                    ],
                    "rules": [
                        {
                            "layer": 1,
                            "timeout": 5
                        },
                        {
                            "layer": 2,
                            "timeout": 10
                        },
                        {
                            "layer": 3,
                            "timeout": 15
                        }
                    ],
                    "repeat": 0
                },
                "id": "23szYVd6nS0+5quLFpSfOjZbG0M9840NMB2GNtiNRscDQ=",
                "current_layer": 1,
                "status": "acknowledged"
            }
        ],
        "d_user_id": "usr_0000214",
        "description": "Node 2-4 have been in a critical state for over 5 minutes.",
        "id": "inc_ByBRdLYZm",
        "tags": [],
        "title": "Servers Outage"
    }
}

Custom Format

Outgoing webhooks can also send data in a custom format. The request is still a POST request and must be in JSON format.

You can edit the format in the Template (JSON) section of the integration settings. Templates support Handlebars substitution with the event and incident objects. You can additionally use any handlebars-helpers to support any logic.

Note: Use the triple-stash {{{ }}} operator to bypass URL encoding.
  • Plain JSON {{{JSONstringify incident}}}
  • Slack (Incoming Webhook) {"text": "<https://app.pagertree.com/#/incident/{{incident.id}}|{{incident.title}}> has been {{replace event.type "incident." ""}}"}

Troubleshooting Templates

If for any reason you do not receive the webhook with a custom template, it is likely you have a formatting error. On the integration page, look at the integration’s logs.

  1. If you do not see a log, ensure the integration is enabled
  2. If you do see a log, view the log by clicking the log link. An error should be provided in the status field in the content section on the right hand side.

Applicable Events

Currently PagerTree support 6 events:

  1. incident.created - fired exactly once, when the incident is created in the database
  2. incident.acknowledged - fired 0-1 times, when the incident is acknowledged
  3. incident.input.rejected - can be fired 0-N times, when the incident is rejected by a user.
  4. incident.timeout - can be fired 0-M times, when an incident layer times out and moves to the next escalation layer
  5. incident.resolved - fired 0-1 times, when the incident is resolved
  6. incident.dropped - fied 0-1 times, when the incident is dropped

It is possible to configure more events, but must be done through special request. If you need extra events, please send support@pagertree.com an email stating which events you need added.

Successful Responses And Limitations

PagerTree considers any response in the 2xx family a successful response. If your endpoint sends any other response PagerTree will consider it a failure. If your endpoint consistently fails for more that 3 consecutive days, PagerTree will automatically disable your outgoing webhook integration.

Your endpoint is expected to respond within 5 seconds. If you endpoint does not respond within the timeout period it will be considered a failure.

The outgoing webhook integration will not follow redirects.