Webhooks: Sending Status Data to Your System

Configuration

Configure Alert Endpoints

Route PingKit status updates directly to your internal dashboards, Slack workspaces, or custom incident management pipelines.

Enter your HTTPS endpoint in the webhook receiver field. PingKit validates the URL upon save and sends a test event containing your workspace ID and a timestamp. Supported methods include POST with JSON content-type. If your endpoint requires authentication, append your bearer token to the header configuration panel.

Data Format

JSON Payload Structure

Every webhook delivery follows a strict schema designed for machine parsing and seamless integration with tools like Datadog, PagerDuty, or custom Node.js listeners.

The envelope contains a top-level event_type field, followed by monitor_id, status, timestamp, and metadata. Below is a production example from a failed TLS handshake on checkout.payment-gateway.net:

{
  "event_type": "status_change",
  "monitor_id": "mon_8f3a2c91b4",
  "status": "down",
  "previous_status": "up",
  "timestamp": "2024-05-18T14:32:09Z",
  "metadata": {
    "endpoint": "https://checkout.payment-gateway.net",
    "latency_ms": 0,
    "error_code": "TLS_CERT_EXPIRED",
    "region": "eu-west-1",
    "attempt": 1
  }
}

Arrays are used for multi-region checks. If a monitor spans us-east-1, ap-south-1, and eu-central-1, the metadata.regions array will list individual response codes and failure points.

Verification

Webhook Signature Verification

Protect your ingestion pipeline with HMAC-SHA256 signature validation. PingKit signs every outgoing payload using your workspace secret key.

Locate the x-pingkit-signature header in each incoming request. The value is formatted as t=1716045129,v1=a8b3c2d1e4f5. To verify, concatenate the timestamp, a colon, and the raw request body. Generate an HMAC-SHA256 hash using your secret key and compare it against the v1 payload. Reject requests where the timestamp exceeds 5 minutes to prevent replay attacks.