Webhooks

Paqet delivers monitoring events to an HTTPS endpoint you control, signed so you can verify they came from us.

Webhooks are an Enterprise feature. Create and manage them in Console → Webhooks — each webhook has a URL, a destination type (Generic, Slack, or Discord), and a set of event types it subscribes to. A generated signing secret is shown once at creation.

How delivery works

• When a subscribed event fires, Paqet sends an HTTP POST to your URL with a JSON body.
• Any 2xx response counts as delivered. Anything else — or a timeout — is a failure and is retried.
• Delivery is per-webhook: if three of your webhooks subscribe to the same event, each gets its own POST and its own retry schedule.
• Every attempt (request, response, status, duration) is recorded under Console → Webhooks → Deliveries.

Payload envelope

Generic webhooks receive a signed envelope. The event-specific data is nested under Data; the envelope keys are PascalCase.

{
  "Id": "5b6e1e3a-9c7d-4f2a-8b1e-2c3d4e5f6a7b",
  "Type": "incident.created",
  "CreatedAt": "2026-09-01T12:00:00+00:00",
  "Data": {
    "DomainId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "Host": "example.com",
    "CheckType": "HTTP",
    "Status": "Error",
    "Title": "HTTP Error: 503 Service Unavailable",
    "Summary": "The endpoint returned 503 for 3 consecutive checks."
  }
}

Headers

Verifying signatures

Recompute the signature yourself and compare it to v1 — never trust the header without checking it.

X-Paqet-Signature: t=1756728000,v1=a29680b4c1f2...

Formula

v1 = HMAC_SHA256(secret, t + "." + rawRequestBody)   // lowercase hex

Node.js

const crypto = require("crypto");

function verify(secret, rawBody, signatureHeader) {
    const parts = Object.fromEntries(signatureHeader.split(",").map(p => p.split("=")));
    const expected = crypto
        .createHmac("sha256", secret)
        .update(`${parts.t}.${rawBody}`)
        .digest("hex");

    // Reject old timestamps to blunt replay attacks (Paqet uses a 5-minute tolerance).
    if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;

    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

• Hash the raw request body, byte-for-byte — not a re-serialized copy.
• Use a constant-time comparison.
• Reject deliveries whose t is more than 5 minutes from your clock.

Retries

A failed delivery is retried up to 5 times with a fixed backoff:

attempt 1  →  immediately
attempt 2  →  +30 seconds
attempt 3  →  +2 minutes
attempt 4  →  +10 minutes
attempt 5  →  +30 minutes
attempt 6  →  +2 hours

After that the delivery is abandoned. Make your handler idempotent on X-Paqet-Delivery — a retry can arrive after your endpoint has, in fact, already processed the first attempt. If your Enterprise plan lapses, pending retries stop and the webhook is disabled.

Events

Subscribe to events per-webhook in Console → Webhooks.

Event payloads

Incident

Sent for incident.created, incident.resolved, monitor.down, monitor.up, ssl.expiring, ssl.expired, and domain.expiring.

{
  "DomainId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "Host": "example.com",
  "CheckType": "HTTP",
  "Status": "Error",
  "Title": "HTTP Error: 503 Service Unavailable",
  "Summary": "The endpoint returned 503 for 3 consecutive checks."
}

Maintenance

Sent for maintenance.started and maintenance.finished.

{
  "DomainId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "Host": "example.com",
  "StartsAt": "2026-09-02T01:00:00+00:00",
  "EndsAt": "2026-09-02T03:00:00+00:00",
  "Reason": "Database migration"
}

Assistant analysis

Sent for assistant.analysis.completed.

{
  "AnalysisId": "d4a1c9f0-6b2e-4a1d-9c3f-1e2d3c4b5a60",
  "OrganizationId": "7b2c1a90-3f4e-4d5c-8a1b-2c3d4e5f6a7b",
  "CycleDate": "2026-09-01",
  "TriggerType": "Scheduled",
  "Verdict": "NeedsAttention",
  "Confidence": "High",
  "Severity": "Medium",
  "Headline": "Unexpected certificate issuance for api.example.com",
  "Reasoning": "A certificate for api.example.com was issued by a CA this organization has not used before...",
  "SignalCount": 3,
  "ConsoleUrl": "https://app.paqet.io/console/assistant?open=d4a1c9f0-6b2e-4a1d-9c3f-1e2d3c4b5a60"
}

Assistant verdicts, confidence & severity

The Assistant reviews monitoring signals and produces three graded fields, used on both the webhook payload and the Assistant API.

• Verdict — Benign (matches this organization's established patterns; no webhook is sent), NeedsAttention (review this), Uncertain (the Assistant could not confidently rule it benign — treat it as "look, but don't panic", not as a confirmed problem).
• Confidence — Low / Medium / High: how sure the Assistant is of that verdict.
• Severity — Info / Low / Medium / High / Critical: how urgent the finding is if it is real.

Slack & Discord

Webhooks with a Slack or Discord destination receive that platform's native message format (Block Kit / embeds) instead of the signed envelope, so they render as a readable message in-channel. The same X-Paqet-* headers are still sent and still signed. If you want the raw JSON envelope, use a Generic destination.