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",
        "s_log_id": "log_0123456",
        "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",

         // the following will only be sent
         // if linked data is enabled
        "source": {...user or integration},
        "s_log": {...log},
        "d_team": {...team},
        "d_user": {...user}
    }
}

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.

Additionally, you can use d_team, d_user, source, s_log attributes to get referenced objects.

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." ""}}"}
  • Referenced objects {"text": "The incident has been acknowledged by {{incident.d_user.name}} ({{incident.d_user.email}})"}

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.

Linked Data

Linked data is a convenience option that embeds referenced objects. Linked data will send the following extra fields d_team, d_user, source, s_log. Respectfully these are the team referenced by d_team_id, user referenced by d_user_id, user or integration referenced by source_id, and the log referenced by s_log_id.

To enable sending of linked data:

  1. Edit the integration
  2. Enable the Linked Data switch Enable Linked Data
  3. Click Save
Note: Linked data is only applicable if a custom format is not used.

Applicable Events

Currently PagerTree support 7 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 - fired 0-1 times, when the incident is dropped
  7. incident.handoff - fired 0-N times, when the incident is handed off

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.