State change webhooks
Pingdom’s state change webhooks, or webhooks for short, let you programmatically act on state changes that occur on your uptime or transaction checks. For uptime checks, a state change is when the check changes state from UP to DOWN or vice versa. For transaction checks, a state change is when the check changes state from SUCCESS to FAILING or vice versa.
Webhooks are a perfect solution when you want to create a script or service that executes when a monitored site goes down or a monitored transaction cannot finish – all without having to parse alert messages or continuously poll the Pingdom API for updates.
What is a webhook?
A webhook is an HTTP POST request that Pingdom sends to a URL of your choosing when a certain event occurs. This request is accompanied by a payload of data in the POST body related to the event. A state change webhook is triggered when an uptime or transaction check changes state from UP/SUCCESS to DOWN/FAILING or vice versa.
BeepManager webhooks
State change webhooks should not be confused with BeepManager webhooks. State change webhooks trigger immediately when an uptime or transaction check changes state, as opposed to a BeepManager webhook that triggers only if you 1) use BeepManager as your alerting system and 2) BeepManager is set up to alert a user or alerting endpoint that is configured to trigger a webhook.This distinction makes the use cases for state change webhooks and BeepManager webhooks different. State change webhooks are perfect when you want to create an integration with Pingdom that reacts upon state changes, e.g. to reboot a server, make a phone call, send a push notification to a mobile device, etc. BeepManager webhooks, on the other hand, are perfect when you want to create an integration with Pingdom that e.g. logs the resolution time of triggered incidents.
How to set up a state change webhook
This documentation is focused on how to consume state change webhooks. For information on how to create a webhook in My Pingdom and use it for your checks, please see this FAQ article.
How to consume a state change webhook
Pingdom’s state change webhooks are HTTP POST requests with Content-Type: application/json. The POST body contains a JSON data object with information specific to the check type that triggered the webhook (see below).
Alert bundling
For BeepManager alerts, we support the concept of alert bundling (also known as alert flood protection). This means that data is grouped if multiple incidents are triggered simultaneously. This concept is not applicable to state change webhooks. Every HTTP request will only contain info about one state change.
Examples of webhook JSON output for uptime checks
Note on sending a test webhook from within My Pingdom:
Response parameters first_probe and second_probe will be empty. They represent the first and second opinion to confirm that a state change has actually occurred. Response parameters long_description will have the value “This is a test message triggered by a user in My Pingdom” and description will have the value “test”.
When an uptime check changes state from DOWN to UP, parameters long_description and description will have the value “OK”. If a probe server does not have an IPv6 address, that parameter will be an empty string.
HTTP check [POST]
{
"check_id": 12345,
"check_name": "Name of HTTP check",
"check_type": "HTTP",
"check_params": {
"basic_auth": false,
"encryption": true,
"full_url": "https://www.example.com/path",
"header": "User-Agent:Pingdom.com_bot",
"hostname": "www.example.com",
"ipv6": false,
"port": 443,
"url": "/path"
},
"tags": [
"example_tag"
],
"previous_state": "UP",
"current_state": "DOWN",
"importance_level": "HIGH",
"state_changed_timestamp": 1451610061,
"state_changed_utc_time": "2016-01-01T01:01:01",
"long_description": "Long error message",
"description": "Short error message",
"first_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Stockholm, Sweden"
},
"second_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Austin, US",
"version": 1
}
}HTTP Custom check [POST]
{
"check_id": 12345,
"check_name": "Name of HTTP Custom check",
"check_type": "HTTP_CUSTOM",
"check_params": {
"basic_auth": false,
"encryption": false,
"full_url": "https://www.example.com/path",
"hostname": "www.example.com",
"ipv6": false,
"port": 80,
"url": "/"
},
"tags": [
"example_tag"
],
"previous_state": "UP",
"current_state": "DOWN",
"importance_level": "HIGH",
"state_changed_timestamp": 1451610061,
"state_changed_utc_time": "2016-01-01T01:01:01",
"long_description": "Long error message",
"description": "Short error message",
"first_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Stockholm, Sweden"
},
"second_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Austin, US",
"version": 1
}
}TCP check [POST]
{
"check_id": 12345,
"check_name": "Name of TCP check",
"check_type": "PORT_TCP",
"check_params": {
"hostname": "www.example.com",
"basic_auth": false,
"ipv6": false,
"port": 80
},
"tags": [
"example_tag"
],
"previous_state": "UP",
"current_state": "DOWN",
"importance_level": "HIGH",
"state_changed_timestamp": 1451610061,
"state_changed_utc_time": "2016-01-01T01:01:01",
"long_description": "Long error message",
"description": "Short error message",
"first_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Stockholm, Sweden"
},
"second_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Austin, US",
"version": 1
}
}Ping check [POST]
{
"check_id": 12345,
"check_name": "Name of Ping check",
"check_type": "PING",
"check_params": {
"hostname": "www.example.com",
"basic_auth": false,
"ipv6": false
},
"tags": [
"example_tag"
],
"previous_state": "UP",
"current_state": "DOWN",
"importance_level": "HIGH",
"state_changed_timestamp": 1451610061,
"state_changed_utc_time": "2016-01-01T01:01:01",
"long_description": "Long error message",
"description": "Short error message",
"first_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Stockholm, Sweden"
},
"second_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Austin, US",
"version": 1
}
}DNS check [POST]
{
"check_id": 12345,
"check_name": "Name of DNS check",
"check_type": "DNS",
"check_params": {
"hostname": "www.example.com",
"basic_auth": false,
"expected_ip": "123.4.5.6",
"ipv6": false,
"nameserver": "example.com"
},
"tags": [
"example_tag"
],
"previous_state": "UP",
"current_state": "DOWN",
"importance_level": "HIGH",
"state_changed_timestamp": 1451610061,
"state_changed_utc_time": "2016-01-01T01:01:01",
"long_description": "Long error message",
"description": "Short error message",
"first_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Stockholm, Sweden"
},
"second_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Austin, US",
"version": 1
}
}UDP check [POST]
{
"check_id": 12345,
"check_name": "Name of UDP check",
"check_type": "UDP",
"check_params": {
"hostname": "www.example.com",
"basic_auth": false,
"expect": "string to expect",
"ipv6": false,
"port": 80,
"send": "string to send"
},
"tags": [
"example_tag"
],
"previous_state": "UP",
"current_state": "DOWN",
"importance_level": "HIGH",
"state_changed_timestamp": 1451610061,
"state_changed_utc_time": "2016-01-01T01:01:01",
"long_description": "Long error message",
"description": "Short error message",
"first_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Stockholm, Sweden"
},
"second_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Austin, US",
"version": 1
}
}SMTP check [POST]
{
"check_id": 123456,
"check_name": "Name of SMTP check",
"check_type": "SMTP",
"check_params": {
"basic_auth": false,
"encryption": false,
"hostname": "www.example.com",
"ipv6": false,
"port": 25
},
"tags": [
"example_tag"
],
"previous_state": "UP",
"current_state": "DOWN",
"importance_level": "HIGH",
"state_changed_timestamp": 1451610061,
"state_changed_utc_time": "2016-01-01T01:01:01",
"long_description": "Long error message",
"description": "Short error message",
"first_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Stockholm, Sweden"
},
"second_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Austin, US",
"version": 1
}
}POP3 check [POST]
{
"check_id": 12345,
"check_name": "Name of POP3 check",
"check_type": "POP3",
"check_params": {
"basic_auth": false,
"encryption": false,
"hostname": "www.example.com",
"ipv6": false,
"port": 110
},
"tags": [
"example_tag"
],
"previous_state": "UP",
"current_state": "DOWN",
"importance_level": "HIGH",
"state_changed_timestamp": 1451610061,
"state_changed_utc_time": "2016-01-01T01:01:01",
"long_description": "Long error message",
"description": "Short error message",
"first_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Stockholm, Sweden"
},
"second_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Austin, US",
"version": 1
}
}IMAP check [POST]
{
"check_id": 12345,
"check_name": "Name of IMAP check",
"check_type": "IMAP",
"check_params": {
"hostname": "www.example.com",
"basic_auth": false,
"encryption": false,
"ipv6": false,
"port": 143
},
"tags": [
"example_tag"
],
"previous_state": "UP",
"current_state": "DOWN",
"importance_level": "HIGH",
"state_changed_timestamp": 1451610061,
"state_changed_utc_time": "2016-01-01T01:01:01",
"long_description": "Long error message",
"description": "Short error message",
"first_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Stockholm, Sweden"
},
"second_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Austin, US",
"version": 1
}
}Examples of webhook JSON output for transaction checks
Note on sending a test webhook from within My Pingdom:
Response parameters first_probe and second_probe will be empty. They represent the first and second opinion to confirm that a state change has actually occurred.
When a transaction check changes state from FAILING to SUCCESS, parameters long_description and description will be empty. If a probe server does not have an IPv6 address, that parameter will be an empty string.
Transaction check [POST]
{
"check_id": 12345,
"check_name": "Name of transaction check",
"check_type": "TRANSACTION",
"check_params": {
"encryption": true,
"port": 443,
"url": "https://www.example.com/"
},
"tags": [
"example_tag"
],
"previous_state": "FAILING",
"current_state": "SUCCESS",
"importance_level": "HIGH",
"state_changed_timestamp": 1451610061,
"state_changed_utc_time": "2016-01-01T01:01:01",
"description": "Error message",
"first_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Stockholm, Sweden"
},
"second_probe": {
"ip": "123.4.5.6",
"ipv6": "2001:4800:1020:209::5",
"location": "Austin, US",
"version": 1
}
}