Skip to main content
WP HealthKit

Webhooks

Receive real-time notifications when audits complete — no polling required. Send native Slack, Mattermost or Discord messages with a payload template, or post the raw JSON envelope to your own endpoint.

Events

Subscribe to one or more of these event types when registering a webhook endpoint.

EventDescription
audit.completedFired when an audit finishes successfully. Includes the full result summary.
audit.failedFired when an audit fails due to an error (e.g. invalid ZIP, API timeout).
claim.challengedFired by Living Audits when newer ground truth challenges a claim in one of your audits.

Registration

Register a webhook endpoint using the API. Your URL must use HTTPS and return a 2xx status within 10 seconds.

curl -X POST https://wphealthkit.com/api/v1/webhooks \
  -H "Authorization: Bearer whk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.slack.com/services/T.../B.../xxx",
    "events": ["audit.completed", "audit.failed", "claim.challenged"],
    "template": "slack"
  }'

WP HealthKit generates the signing secret — you do not supply one. It is returned once, in the create response, and cannot be read back:

{
  "data": {
    "id": "8f1d0c9e-6a2b-4a4f-9d3e-1c2b3a4d5e6f",
    "url": "https://hooks.slack.com/services/T.../B.../xxx",
    "events": ["audit.completed", "audit.failed", "claim.challenged"],
    "template": "slack",
    "active": true,
    "signingSecret": "whsec_..."
  },
  "error": null,
  "meta": { "timestamp": "2025-04-10T12:00:00.000Z" }
}

Update an endpoint without rotating the secret — change the URL, subscribed events, template, or pause delivery:

curl -X PATCH https://wphealthkit.com/api/v1/webhooks/8f1d... \
  -H "Authorization: Bearer whk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["audit.completed"], "template": "mattermost", "active": true }'

Payload Templates

template decides the shape of the POST body. Signatures are computed over the rendered body, so verify the raw request body regardless of template.

TemplateBody
generic{ event, data, timestamp } — your own integration.
slack{ text, attachments } with a "View report" button.
mattermost{ text, attachments } with a linked title (Mattermost ignores Slack action buttons).
discord{ embeds[] } with a colour matched to risk.

Mattermost incoming webhooks accept Slack-compatible bodies. Add the webhook URL from Mattermost (Integrations → Incoming Webhooks) and choose the Mattermost template.

Payload Format

Payloads are sent as JSON via HTTP POST. The generic envelope contains the event type, the event-specific data, and a timestamp. Slack, Mattermost and Discord templates render the same facts in each product's native message shape.

audit.completed

{
  "event": "audit.completed",
  "data": {
    "auditId": "ce612d59-1a44-4b34-b998-d02738a22553",
    "pluginName": "Contact Form 7",
    "pluginSlug": "contact-form-7",
    "overallRisk": "LOW",
    "findingsCount": 3,
    "grade": "A",
    "repo": "acme/my-plugin",
    "commit": "9f2c1ab"
  },
  "timestamp": "2026-11-18T12:01:14.000Z"
}

audit.failed

{
  "event": "audit.failed",
  "data": {
    "auditId": "6a9f0d42-7a0e-4b3f-8d1e-2c3b4a5d6e7f",
    "pluginName": "broken-plugin",
    "error": "Could not extract ZIP — invalid archive"
  },
  "timestamp": "2026-11-18T12:00:58.000Z"
}

claim.challenged

{
  "event": "claim.challenged",
  "data": {
    "auditId": "ce612d59-1a44-4b34-b998-d02738a22553",
    "pluginName": "Example Plugin",
    "pluginSlug": "example-plugin",
    "claimId": "clm_36d6ca5f751d4054a6efb7833edb3912",
    "challenge": "PHP 7.4 reached end-of-life on 2022-11-28 — this claim now implies an unsupported runtime",
    "evidenceSource": "endoflife.date/api/php.json"
  },
  "timestamp": "2026-07-30T09:15:22.000Z"
}

Fired by Living Audits when Reverify challenges a claim from one of your audits against newer ground truth. The original audit is never modified — the challenge attaches alongside it.

Signature Verification

WP HealthKit generates a signing secret when the webhook is created and signs every delivery with HMAC-SHA256 over the raw request body. Verify the signature to ensure the request originated from us and has not been tampered with.

Always verify signatures

Skipping signature verification allows anyone who knows your endpoint URL to send forged payloads.

The signature is sent in the X-WPHK-Signature header as lower-case hex (the X-WPHK-Event header carries the event name).

Node.js (Express)

import crypto from "crypto";

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload, "utf8")
    .digest("hex");

  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express handler
app.post("/webhooks/wphk", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-wphk-signature"] as string;
  const isValid = verifyWebhookSignature(req.body.toString(), sig, process.env.WPHK_WEBHOOK_SECRET!);

  if (!isValid) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const event = JSON.parse(req.body.toString());
  console.log("Received event:", event.event);

  res.json({ received: true });
});

PHP (WordPress)

add_action('rest_api_init', function() {
  register_rest_route('my-plugin/v1', '/wphk-webhook', [
    'methods'  => 'POST',
    'callback' => 'handle_wphk_webhook',
    'permission_callback' => '__return_true',
  ]);
});

function handle_wphk_webhook(WP_REST_Request $request) {
  $body = $request->get_body();
  $sig  = $request->get_header('x-wphk-signature');
  $secret = defined('WPHK_WEBHOOK_SECRET') ? WPHK_WEBHOOK_SECRET : '';

  $expected = hash_hmac('sha256', $body, $secret);

  if (!hash_equals($expected, $sig ?? '')) {
    return new WP_Error('invalid_signature', 'Signature mismatch', ['status' => 401]);
  }

  $event = json_decode($body, true);
  // Handle event...
  return ['received' => true];
}

Retry Policy

If your endpoint returns a non-2xx status code or does not respond within 10 seconds, WP HealthKit attempts delivery three times in total.

AttemptDelay after failure
1 (initial)Immediate
25 seconds
330 seconds

The final outcome is recorded for each delivery. After 10 consecutive failed deliveries the webhook is automatically disabled — recreate or re-enable it once your endpoint is healthy. A manual test is available from Settings → Webhooks.

Register your first webhook

Use the API or the dashboard to manage webhook endpoints.