Webhooks

Webhooks push events to your endpoint the moment they happen, so you do not have to poll. WPOS signs every delivery so you can prove it came from us. You set one endpoint per partner, either in the dashboard or with WPOS.

Set your endpoint

In the Partner Dashboard, open Settings, then set your webhook URL. WPOS generates a signing secret and shows it to you exactly once. Store it now: it is never shown again, and changing the URL rotates it. The endpoint must be an https:// URL.

Events

site.registered

A WordPress site connected to one of your managed accounts.

{
  "event": "site.registered",
  "timestamp": "2026-08-08T...",
  "data": { "accountId": "acc_...", "externalRef": "ws_123", "siteId": "site_...", "siteUrl": "https://customer.com", "siteTitle": "Customer Co", "pluginVersion": "2.3.0" }
}

credits.low

An account’s balance crossed below ten percent of its plan’s monthly credits. Fires once per billing cycle, so you can top the account up in time.

{
  "event": "credits.low",
  "timestamp": "2026-08-08T...",
  "data": { "accountId": "acc_...", "externalRef": "ws_123", "balance": 45, "monthlyCredits": 500 }
}

job.completed

A build job reached a terminal status. Fires on succeeded, failed, timeout, and cancelled, and carries the same result as the job poll.

{
  "event": "job.completed",
  "timestamp": "2026-08-08T...",
  "data": { "jobId": "job_...", "externalRef": "job_001", "siteId": "site_...", "accountId": "acc_...", "status": "succeeded", "result": { "summary": "...", "changes": [], "warnings": [] }, "creditsConsumed": 6 }
}

The request

Every delivery is a POST to your URL with these headers:

Header	Value
`Content-Type`	`application/json`
`X-WPOS-Event`	The event name, for example `job.completed`.
`X-WPOS-Signature`	`sha256=<hex>`, an HMAC-SHA256 of the raw request body keyed with your webhook secret.

The body is { "event": "...", "timestamp": "...", "data": { ... } }.

Verify the signature

Always verify before you trust a delivery. Compute the HMAC over the raw body and compare it, in constant time, to the header.

import crypto from 'crypto';

// req.rawBody is the exact bytes WPOS sent. Do not re-serialize the parsed JSON.
function verifyWposWebhook(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');
  const a = Buffer.from(signatureHeader || '', 'utf8');
  const b = Buffer.from(expected, 'utf8');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Verify against the raw request body, not a re-serialized copy of the parsed JSON. If your framework parses the body before you see it, capture the raw bytes (for example Express’s express.json({ verify }) hook) so the HMAC matches.

Retries and delivery

WPOS expects a 2xx promptly. Deliveries time out after eight seconds. On any failure or non-2xx, WPOS retries twice: about one minute later, then about five minutes after that. After the third attempt the delivery is marked failed. Make your handler idempotent: identify the work by jobId or siteId and tolerate a repeat.

Debug deliveries

The Settings page in the dashboard shows a live log of recent deliveries with the event, attempt count, outcome, and the failure reason on any that did not land. Use it to confirm your endpoint is reachable and returning 2xx.

API reference

Every endpoint, scope, error, and limit in one place.

Overview

Get started

Guides

Reference

Set your endpoint

Events

The request

Verify the signature

Retries and delivery

Debug deliveries

Next

API reference

​Set your endpoint

​Events

​The request

​Verify the signature

​Retries and delivery

​Debug deliveries

​Next

API reference

Set your endpoint

Events

The request

Verify the signature

Retries and delivery

Debug deliveries

Next