Webhooks

Webhooks are used to process real-time check updates, for example when a check for your website fails. The URL you have set up in your account will be used and sends you all the data you need to know. Whenever you receive a POST call from us to the webhook URL you need to return a 200 response. Otherwise we continue sending the webhook until we receive a 200 response.

Each webhook consists of two parts. The body with the information about the check of the website and a bunch of headers. You can read more about the headers below.

PingPing sends different webhooks for different updates. Below you can find all the five webhooks we send to your account depending on your websites.

¶Webhook Types

¶Uptime Website – Down

The downtime webhook is called whenever your website is down. This will give you all the data you need to take action automatically if needed.

        
        {
    "check": {
        "meta": {
            "http_status_code": 400,
            "detected_by": "Helsinki",
            "verified_via": "Sydney",
        },
        "name": "uptime",
        "error": "400 - Bad Request",
        "status": "nok",
        "last_check_at": "2020-03-28 22:02:31"
    },
    "monitor": {
        "id": 3,
        "url": "https://example.com",
        "alias": "Example"
    }
}
    

¶Uptime Website – Recovered

Whenever your website is up again, the opposite of the downtime webhook is called. The uptime webhook sends you the following data. Note that the we also send the downtime time in the meta data. This will always be available in the H:i:s format.

        
        {
    "check": {
        "meta": {
            "http_status_code": 200,
            "downtime": "00:01:12"
        },
        "name": "uptime",
        "status": "ok",
        "last_check_at": "2020-03-28 22:03:43"
    },
    "monitor": {
        "id": 3,
        "url": "https://example.com",
        "alias": "Example"
    }
}
    

¶SSL Certificate – Invalid

The certificate check is very useful for automating renewal. Whenever the certificate is invalid or expired you get the following data in the webhook.

        
        {
    "check": {
        "name": "certificate_health",
        "error": "Hostname staging.example.com does not match the certificate. It matches to these domains only: example.com",
        "status": "nok",
        "last_check_at": "2020-03-29 11:00:02"
    },
    "monitor": {
        "id": 4,
        "url": "https://staging.example.com",
        "alias": "Example Staging"
    }
}
    

¶SSL Certificate – Recovered

The opposite of the invalid certificate webhook is the recovered webhook. This also gives back some more information about your certificate which can be useful. For example, the date that it will expire.

        
        {
    "check": {
        "meta": {
            "issuer": "Let's Encrypt Authority X3",
            "signature_algorithm": "RSA-SHA256",
            "valid_from": "2020-02-25 09:53:41",
            "valid_to": "2020-05-25 09:53:41"
        },
        "name": "certificate_health",
        "status": "ok",
        "last_check_at": "2020-03-28 14:28:58"

    },
    "monitor": {
        "id": 3,
        "url": "https://example.com",
        "alias": "Example"
    }
}
    

¶SSL Certificate – Expires soon

Whenever your certificate is up for renewal we send you a webhook as well. This way you can act in time to renew your certificate and never have problems with this. We will only fire this whenever you have set up a notification threshold for the certificate of that monitor. The payload for this webhook looks like this:

        
        {
    "check": {
        "meta": {
            "expires_in_days" => 7,
            "issuer": "Let's Encrypt Authority X3",
            "signature_algorithm": "RSA-SHA256",
            "valid_from": "2020-03-25 09:53:41",
            "valid_to": "2020-04-25 09:53:41"
        },
        "name": "certificate_health",
        "status": "ok",
        "last_check_at": "2020-03-28 14:28:58"

    },
    "monitor": {
        "id": 3,
        "url": "https://example.com",
        "alias": "Example"
    }
}
    

¶Webhook Headers

For security and informational reasons, we also send a bunch of headers along with the webhook. You may use them in any way.

        
        POST https://example.com/webhook

Content-Type: application/json,
User-Agent: pingping.io/1.0,
X-PingPing-Current-Try: 8,
X-PingPing-Parent-Webhook: 12,
X-PingPing-Signature: bb0f63fc6887fb2fd80509804adba87ef0f9eb9b,
X-PingPing-Webhook: 20
    

¶Verifying the webhook

PingPing signs all webhooks. The signature can be found in the X-PingPing-Signature header. This signature is a sha1 hash from the body of the webhook signed with your API-key. If they don't match you shouldn't accept the request.

In the end, we sign it like this:

        
        hash_hmac('sha1', $body, $yourApiKey);