Webhooks are automated messages sent from Siteligent to your server when specific events occur. Think of them as "reverse API calls". Instead of your application repeatedly asking Siteligent for data, Siteligent automatically sends the relevant information to your endpoint when an event occurs.
Example: When a backup completes on your WordPress site, Siteligent can instantly notify your monitoring system, Slack integration, or custom application, without requiring polling.
Getting Started
1. Create an Endpoint
Set up a URL on your server that can receive HTTP POST requests.
This could be:
A serverless function
An API endpoint
A web server
A custom application endpoint
For example: https://your-domain.com/webhooks/siteligent
2. Add Webhook Configuration
In Siteligent, click Add Webhook and enter your endpoint URL. Then choose which events you want to receive notifications for.
3. Test Your Integration
Use the Test button to send a sample payload to your endpoint.Verify that your server receives the request and processes the payload correctly.
Payload Structure
Every webhook request includes a JSON payload with the following structure:
{
"event": "backup",
"timestamp": "2024-12-08T10:30:00.000Z",
"data": {
"type": "backup",
"title": "Backup Completed",
"message": "Full backup completed successfully",
"severity": "info",
"timestamp": "2024-12-08T10:30:00.000Z",
"details": {
"backupId": "abc123",
"size": "250MB",
"duration": "45s"
}
},
"site": {
"id": "site-uuid-here",
"name": "My WordPress Site",
"url": "https://example.com"
}
}Field | Description |
| The type of event that triggered the webhook. |
| The ISO 8601 date and time when the event occurred. |
| Event-specific information and details. |
| Information about the affected WordPress site. |
HTTP Headers
Each webhook request includes the following headers:
Content-Type: application/json
User-Agent: Siteligent-Webhook/1.0
X-Siteligent-Event: backup
X-Siteligent-Timestamp: 2024-12-08T10:30:00.000Z
X-Siteligent-Signature: sha256=abc123... (if secret configured)
The X-Siteligent-Signature header is included when a webhook secret has been configured.
Custom Headers
You can also add custom headers in your webhook configuration.
For example, you can use a Bearer token to authenticate requests with your endpoint:
Authorization: Bearer your-token
Signature Verification
When you configure a webhook secret, Siteligent signs each payload using HMAC-SHA256. This allows your application to verify that webhook requests genuinely came from Siteligent.
Important: Always verify webhook signatures in production to protect your endpoint from spoofed or malicious requests.
Node.js
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
const expectedSignature = 'sha256=' +
crypto.createHmac('sha256', secret)
.update(JSON.stringify(payload))
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
// In your endpoint handler:
app.post('/webhook', (req, res) => {
const signature = req.headers['x-siteligent-signature'];
const secret = process.env.WEBHOOK_SECRET;
if (!verifySignature(req.body, signature, secret)) {
return res.status(401).json({ error: 'Invalid signature' });
}
// Process the webhook...
console.log('Event:', req.body.event);
res.status(200).json({ received: true });
});Note: For signature verification to work reliably, your application should verify the signature against the raw request body rather than a re-serialized JSON object. This prevents formatting differences from affecting the signature.
Python
import hmac
import hashlib
import { ErrorMessageHandler } from '@/utils/errorMessages';
def verify_signature(payload, signature, secret):
expected = 'sha256=' + hmac.new(
secret.encode(),
payload.encode(),
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)
# In your Flask endpoint:
@app.route('/webhook', methods=['POST'])
def handle_webhook():
signature = request.headers.get('X-Siteligent-Signature')
if not verify_signature(request.data.decode(), signature, SECRET):
return jsonify({'error': 'Invalid signature'}), 401
data = request.json
print(f"Received event: {data['event']}")
return jsonify({'received': True})
Event Types
When creating a webhook, you can choose which types of events should trigger a notification. Select All Events to receive every supported event, or choose specific categories based on what your integration needs.
All Events
Receive webhook notifications for all supported Siteligent events across security, backups, updates, performance, uptime, and system activity.
Security Events
Receive notifications when Siteligent detects or records a security-related event, such as:
Malware detected on a site
Security or vulnerability alerts
Suspicious login attempts
Other security-related notifications
Backup Events
Receive notifications when a backup-related action occurs, such as:
Backup started
Backup completed successfully
Backup failed
Backup restored
Update Events
Receive notifications when WordPress components are updated, including:
WordPress core updates
Plugin updates
Theme updates
Performance Events
Receive notifications about performance-related activity, such as:
Performance or speed metric updates
Optimization results
Performance alerts
Uptime Events
Receive notifications when there is a change in your site's availability or response time, such as:
Site goes offline
Site comes back online
Slow response times
Availability or uptime alerts
System Events
Receive general Siteligent system notifications that don't fall into the categories above.
Tip: If you're integrating Siteligent with another application, select only the event types your application needs. This helps reduce unnecessary webhook requests and makes your integration easier to manage.
Testing Your Webhook
Before connecting your webhook to a production application, you can use a webhook testing service to confirm that Siteligent is sending requests correctly. These services provide temporary URLs where you can send webhook requests and inspect the headers, payload, and request details.
Create an instant test URL and use it as your Siteligent webhook endpoint. You can then view the requests sent by Siteligent in real time.
Create a temporary mock API endpoint and inspect incoming webhook requests without setting up your own server.
Generate a temporary endpoint for receiving and inspecting HTTP requests.
Useful for testing HTTP requests and viewing the request data received by an endpoint.
Tip: For a quick test, Webhook.site is usually the easiest option. Copy the generated URL, add it as your Siteligent webhook endpoint, and use Test Webhook to send a sample request.
Troubleshooting
If your webhook isn't being delivered successfully, check the following common issues.
Connection Refused
This usually means your server is rejecting incoming requests from Siteligent.
Check that:
Your endpoint URL is correct.
Your server is accessible from the internet.
Your firewall allows incoming HTTP
POSTrequests.Your application is listening on the expected port.
Timeout Errors
Siteligent waits up to 15 seconds for your endpoint to respond. Make sure your endpoint acknowledges the webhook quickly. If your application needs to perform time-consuming work, return a successful response first and process the webhook asynchronously in the background.
HTTPS Required
Webhook endpoints must use HTTPS. The only exception is localhost, which can be used for local testing.
Make sure your SSL certificate is:
Valid
Not expired
Properly configured
Trusted by standard certificate authorities
Failed Deliveries
If a webhook delivery fails, Siteligent automatically retries the request up to 3 times using exponential backoff.
You can check the delivery status and failure count from your webhook configuration.
Best Practices
Following these practices will help keep your webhook integration reliable and secure.
Respond Quickly
Return a 2xx status code as soon as you receive the webhook.
HTTP/1.1 200 OK
You don't need to finish processing the event before responding.
Process Events Asynchronously
For operations that take more time, acknowledge the webhook immediately and process the event using a background job or queue. This prevents unnecessary timeouts and failed deliveries.
Always Verify Signatures
If you've configured a webhook secret, verify the X-Siteligent-Signature header using HMAC-SHA256 before processing the request. This helps ensure that the request was sent by Siteligent and hasn't been modified.
Handle Duplicate Deliveries
Your application should be designed to safely process the same event more than once. Use a unique event identifier when available, or maintain your own mechanism for detecting and ignoring duplicate events.
Log Webhook Requests
Keep logs of incoming webhook requests and their processing status.
This can help you troubleshoot failed deliveries and investigate unexpected behavior.
Subscribe Only to the Events You Need
If your integration only requires backup notifications, subscribe to Backup events instead of All Events. This reduces unnecessary requests and keeps your integration easier to manage.
Quick Reference
Property | Value |
HTTP Method |
|
Content Type |
|
Timeout | 15 seconds |
Maximum Retries | 3 attempts |
Retry Strategy | Exponential backoff |
Signature Algorithm | HMAC-SHA256 |
HTTPS | Required, except |
Example Endpoint
POST https://your-domain.com/webhooks/siteligent
Example Event Header
X-Siteligent-Event: backup
Example Signature Header
X-Siteligent-Signature: sha256=abc123...
Have Questions or Need Help?
If you have questions about setting up webhooks, configuring events, or integrating Siteligent with your application, our support team is here to help.
If you're experiencing issues with webhook delivery or signature verification, please include any relevant error messages and delivery details when contacting us. This will help our team investigate and resolve your issue faster.
Still need assistance? Contact Siteligent Support and we'll be happy to help.