Webhooks

Receive real-time HTTP notifications when specific events occur on your managed WordPress sites. Configure endpoints, verify signatures, and build automated workflows.

ℹ️

Webhooks are available on all Professional and Enterprise plans. Starter plans include up to 5 webhook deliveries per month.

What are Webhooks?

Webhooks allow your application to receive instant notifications when events happen on WordPress sites managed by Wp Admin. Instead of polling our API, we send an HTTP POST request to your configured endpoint whenever a subscribed event triggers.

Common use cases include:

Automating backup verification workflows
Triggering security incident response scripts
Syncing site health metrics with your internal dashboards
Notification routing to Slack, Teams, or custom alerting systems

Configuration

You can register webhooks via the Dashboard or programmatically using our API.

Dashboard Setup

Navigate to Settings → Integrations → Webhooks
Click Add Endpoint
Enter a descriptive name and valid HTTPS URL
Select events you want to subscribe to
Save and copy your secret key for signature verification

API Setup

bash

curl -X POST https://api.wpadmin.com/v1/webhooks \
  -H "Authorization: Bearer $WPADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Alerting",
    "url": "https://hooks.yourcompany.com/wpadmin",
    "events": ["security.alert", "backup.failed", "site.offline"],
    "secret": "whsec_a1b2c3d4e5f6"
  }'

Security & Signature Verification

All webhook requests include a signature header to verify they originated from Wp Admin. We use HMAC-SHA256 with your endpoint's secret key.

The header format is: X-WpAdmin-Signature: t=TIMESTAMP,v1=SIGNATURE

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signatureHeader, secret) {
  const [timestamp, expectedSignature] = signatureHeader.split(',').map(pair => {
    const [key, value] = pair.split('=');
    return [key, value];
  });

  const body = `${timestamp[1]}.${payload}`;
  const computedSignature = crypto
    .createHmac('sha256', secret[1])
    .update(body)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature[1]),
    Buffer.from(computedSignature)
  );
}

⚠️

Important: Always verify signatures server-side. Reject requests that fail verification or exceed a 5-minute timestamp window.

Event Types

Event	Description	Triggers
`site.created`	New WordPress site provisioned	Initial setup completion
`site.updated`	Core, theme, or plugin updated	Manual or automated updates
`security.alert`	Security threat detected	Malware, brute force, vulnerability scan
`backup.completed`	Backup finished successfully	Scheduled or manual backup
`backup.failed`	Backup process failed	Storage limits, permission errors
`performance.optimized`	Performance task completed	Cache flush, DB optimization, image compression
`site.offline` Stable	Site unreachable	Uptime monitor failure
`site.recovered` Stable	Site restored online	After offline event

Payload Examples

Every webhook payload follows a consistent schema:

json

{
  "id": "evt_9f8e7d6c5b4a",
  "type": "security.alert",
  "timestamp": "2025-01-15T14:32:00Z",
  "site_id": "site_x8k2m9p4",
  "domain": "example.com",
  "data": {
    "severity": "high",
    "detection": "suspicious_file_upload",
    "path": "/wp-content/uploads/malware.php",
    "resolved": false,
    "action_taken": "file_quarantined"
  },
  "metadata": {
    "wp_version": "6.4.2",
    "php_version": "8.1",
    "managed_by": "wp-admin-auto"
  }
}

Retry Policy

If your endpoint doesn't respond with a 2xx status code, Wp Admin will retry delivery using exponential backoff:

Attempt 1: Immediately after failure
Attempt 2: 5 minutes later
Attempt 3: 30 minutes later
Attempt 4: 3 hours later

After 4 failed attempts, the webhook will be marked as disabled and you'll receive an email notification. You can manually retry or re-enable from the dashboard.

Troubleshooting

Common Issues

SSL/TLS Errors: Ensure your endpoint uses a valid, publicly accessible HTTPS certificate. We do not support HTTP endpoints.
Timeouts: Respond within 5 seconds. For async processing, return 202 Accepted immediately and handle the payload in the background.
Signature Mismatch: Ensure you're using the exact raw request body (not parsed/modified) and the correct secret key.

bash

# Test your endpoint locally with ngrok
git clone https://github.com/WebhookTest/wpadmin-test.git
cd wpadmin-test
npm install
npm run dev

# Forward to ngrok
ngrok http 3000

# Use the ngrok URL in your webhook configuration

Need help? Check the Webhook Logs in your dashboard for detailed delivery records, response codes, and payload history.