Webhooks: Integration with External Systems

Webhook Setup

Add a webhook destination from your account dashboard under Alerts & Integrations. Each webhook is tied to one or more monitors and fires whenever an alert condition is met or resolved.

Destination URL

Enter the full HTTPS URL of your receiving endpoint. Pulsely requires TLS 1.2 or higher. Both https://hooks.example.com/pulsely and https://api.yourcompany.com/v1/alerts patterns are supported. Self-signed certificates are rejected.

Custom Headers

Attach up to 10 key-value header pairs. Common use cases include Authorization: Bearer sk-xxxx for API keys, X-Slack-Signing-Secret for Slack verification, or Content-Type: application/json (set by default).

Monitoring Scope

Select which monitors trigger this webhook. You can attach it to a single monitor (e.g., api.pulsely.io), an entire project (e.g., "Production Infrastructure"), or define a tag-based rule such as env:prod or tier:critical.

Alert Conditions

Fire on downtime only, on recovery, or on both. You can also enable notifications for degraded performance — for example, when response time exceeds 2 seconds for 3 consecutive checks. Status codes outside the 200–299 range are treated as failures.

Create Webhook View Documentation

Payload Format

Every webhook sends a JSON body with a consistent schema. Below is the exact structure delivered when an alert fires for a monitor going down.

Example: Alert Triggered

{
  "id": "whk_9f8e7d6c5b4a3210",
  "event": "alert.triggered",
  "timestamp": "2025-01-14T09:23:41Z",
  "monitor": {
    "id": "mon_a1b2c3d4e5f6",
    "name": "api.stripe-integration.internal",
    "url": "https://api.stripe-integration.internal/health",
    "project_id": "prj_778899aa",
    "tags": ["env:prod", "service:payments"]
  },
  "alert": {
    "type": "downtime",
    "status_code": 502,
    "response_time_ms": 8432,
    "failure_reason": "Connection timed out",
    "consecutive_failures": 3,
    "last_ok_check": "2025-01-14T09:18:11Z"
  },
  "notification": {
    "severity": "critical",
    "channel": "webhook",
    "webhook_id": "whk_9f8e7d6c5b4a3210"
  }
}

Example: Alert Resolved

{
  "id": "whk_9f8e7d6c5b4a3210",
  "event": "alert.resolved",
  "timestamp": "2025-01-14T09:31:05Z",
  "monitor": {
    "id": "mon_a1b2c3d4e5f6",
    "name": "api.stripe-integration.internal",
    "url": "https://api.stripe-integration.internal/health",
    "project_id": "prj_778899aa",
    "tags": ["env:prod", "service:payments"]
  },
  "alert": {
    "type": "recovery",
    "status_code": 200,
    "response_time_ms": 142,
    "downtime_duration_minutes": 7,
    "consecutive_failures": 0
  },
  "notification": {
    "severity": "info",
    "channel": "webhook",
    "webhook_id": "whk_9f8e7d6c5b4a3210"
  }
}

The event field is always either alert.triggered or alert.resolved. The id field is the unique webhook identifier, useful for deduplication on your end. All timestamps are in ISO 8601 UTC format.

Retry Logic & Delivery Guarantees

Pulsely automatically retries failed webhook deliveries using exponential backoff. You control the maximum number of attempts and the initial delay.

Exponential Backoff Schedule

If your endpoint returns a 5xx status or fails to respond within 10 seconds, Pulsely retries with the following intervals: 30 seconds, 2 minutes, 5 minutes, 15 minutes, 30 minutes, and 1 hour. After the final attempt fails, the webhook is marked as stale and you receive an in-app notification.

Configurable Limits

Set a maximum retry count between 1 and 10. The default is 6 attempts over approximately 2 hours. You can also adjust the initial backoff interval from 10 seconds to 5 minutes. Total delivery window must not exceed 24 hours.

Idempotency & Deduplication

Each retry includes the same id and event values. The request also carries an Idempotency-Key header set to <webhook_id>:<event_id> so your server can safely ignore duplicates. No event is sent more than once with the same idempotency key.

Delivery Logs

Every attempt — successful or failed — is logged with a timestamp, HTTP status code, and response body preview (up to 512 bytes). Access the full delivery history from the webhook details page. Logs are retained for 90 days on all plans.

Configure Webhooks Check Delivery Logs