Configuring Webhooks for Automation

Webhooks let you push monitoring events directly into the workflows your team already relies on. Each endpoint receives a signed JSON payload the moment an incident triggers, resolves, or enters a scheduled maintenance window — no polling required.

Webhook JSON Format

Every webhook POST uses a consistent schema. The event_type field distinguishes between incident.triggered and incident.resolved. Below is a real payload from the api.statuspulse.io endpoint recorded on 2024-08-14 at 03:42 UTC:

{
  "event_type": "incident.triggered",
  "timestamp": "2024-08-14T03:42:17Z",
  "check": {
    "id": "chk_9f8e7d6c5b4a",
    "name": "api.statuspulse.io — HTTPS /health",
    "type": "https",
    "interval_seconds": 60
  },
  "incident": {
    "id": "inc_a1b2c3d4e5f6",
    "status": "investigating",
    "started_at": "2024-08-14T03:42:17Z",
    "duration_seconds": 0,
    "http_status": 502,
    "response_time_ms": 31400,
    "error": "SSL handshake timeout after 30s"
  },
  "status_page": {
    "id": "sp_1234abcd",
    "slug": "status",
    "url": "https://status.example.com"
  }
}

On recovery, the payload mirrors the same structure with event_type: "incident.resolved" and adds resolved_at and total_duration_seconds:

{
  "event_type": "incident.resolved",
  "timestamp": "2024-08-14T04:15:03Z",
  "check": {
    "id": "chk_9f8e7d6c5b4a",
    "name": "api.statuspulse.io — HTTPS /health",
    "type": "https",
    "interval_seconds": 60
  },
  "incident": {
    "id": "inc_a1b2c3d4e5f6",
    "status": "resolved",
    "started_at": "2024-08-14T03:42:17Z",
    "resolved_at": "2024-08-14T04:15:03Z",
    "total_duration_seconds": 1966,
    "http_status": 200,
    "response_time_ms": 142
  },
  "status_page": {
    "id": "sp_1234abcd",
    "slug": "status",
    "url": "https://status.example.com"
  }
}

Secret Token & Signature Verification

Every webhook request includes an X-StatusPulse-Signature-256 header containing an HMAC-SHA256 signature. Generate a secret token from Settings → Webhooks → Security and use it to verify payloads server-side.

Header format:

X-StatusPulse-Signature-256: t=1723607537,v1=a3f1b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2

Verification logic (Node.js):

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const [timestamp, expectedSig] = signature.split(',').map(p => p.split('=')[1]);
  if (Date.now() / 1000 - parseInt(timestamp) > 300) {
    throw new Error('Signature timestamp expired');
  }
  const hmac = crypto.createHmac('sha256', secret)
    .update(timestamp + '.' + payload)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expectedSig), Buffer.from(hmac));
}

The signature is valid for 5 minutes. Reject any request where X-StatusPulse-Signature-256 is missing or does not match your stored secret. StatusPulse supports two active secrets simultaneously, so you can rotate keys without interrupting live integrations.

Integration Examples

POST /rest/api/3/issue
Content-Type: application/json
Authorization: Bearer <jira-token>

{
  "fields": {
    "project": { "key": "OPS" },
    "summary": "🔴 Downtime: " + body.check.name,
    "issuetype": { "name": "Bug" },
    "priority": { "name": "Highest" },
    "labels": ["uptime", "webhook"],
    "description": {
      "type": "doc",
      "content": [{
        "type": "paragraph",
        "content": [{
          "type": "text",
          "text": "Check: " + body.check.name + "\nStatus: " + body.incident.http_status + "\nError: " + body.incident.error + "\nStarted: " + body.incident.started_at
        }]
      }]
    }
  }
}

POST /repos/{owner}/{repo}/dispatches
Authorization: token <github-pat>
Content-Type: application/json

{
  "event_type": "statuspulse-recovery",
  "client_payload": {
    "check_name": body.check.name,
    "incident_id": body.incident.id,
    "duration_seconds": body.incident.total_duration_seconds,
    "resolved_at": body.incident.resolved_at
  }
}

Need help wiring a custom integration? Our webhook documentation covers retry policies (exponential backoff up to 48 hours), idempotency keys, and a live webhook debugger that echoes payloads from your endpoints in real time.