Webhook Setup
Configure webhooks to receive real-time notifications when content is created, published, or updated.
What are Webhooks?
Webhooks allow you to receive HTTP POST notifications whenever specific events occur in your Ranklite account. This enables real-time integrations with your own systems, automation workflows, and custom applications.
Common Use Cases
- Trigger custom workflows when new content is published
- Update external databases with article metadata
- Send notifications to Slack, Discord, or other platforms
- Sync content status across multiple systems
- Track content performance in custom analytics tools
Creating a Webhook
Navigate to Webhooks Settings
Go to your Dashboard → Settings → Webhooks or access directly through the Integrations menu.
Click "Add Webhook"
Click the "Add New Webhook" button to open the configuration form.
Configure Webhook Details
Endpoint URL
Your server endpoint that will receive webhook payloads (must use HTTPS)
https://your-domain.com/api/webhooks/rankliteEvents to Subscribe
Select which events should trigger this webhook
Description (Optional)
Add a description to help identify this webhook
Save and Get Signing Secret
After saving, you'll receive a signing secret. Store this securely - you'll need it to verify webhook authenticity.
Webhook Payload Structure
All webhooks send a JSON payload with this structure:
{
"id": "evt_1234567890",
"type": "article.published",
"created": 1734134400,
"data": {
"article": {
"id": "art_abc123",
"title": "Complete Guide to SEO in 2025",
"url": "https://example.com/seo-guide-2025",
"status": "published",
"published_at": "2025-12-14T10:00:00Z",
"keywords": ["seo", "search engine optimization"],
"word_count": 2500
}
}
}Testing Your Webhook
Use the test functionality to verify your endpoint is working correctly:
- 1
Click "Test Webhook"
This sends a sample payload to your endpoint
- 2
Verify Receipt
Check your server logs to confirm the payload was received
- 3
Respond with 200
Your endpoint must return a 200 status code within 5 seconds
Example Implementation
Here's a basic Node.js/Express example:
import express from 'express';
import crypto from 'crypto';
const app = express();
app.use(express.json());
// Verify webhook signature
function verifySignature(payload, signature, secret) {
const hmac = crypto.createHmac('sha256', secret);
const digest = hmac.update(payload).digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(digest)
);
}
app.post('/api/webhooks/ranklite', (req, res) => {
const signature = req.headers['x-ranklite-signature'];
const payload = JSON.stringify(req.body);
// Verify the webhook is from Ranklite
if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
const { type, data } = req.body;
// Handle different event types
switch (type) {
case 'article.published':
console.log('Article published:', data.article.title);
// Add your logic here
break;
case 'article.updated':
console.log('Article updated:', data.article.title);
break;
}
// Always respond with 200
res.status(200).send('Webhook received');
});
app.listen(3000);Best Practices
Respond Quickly
Process webhooks asynchronously and respond with 200 immediately
Verify Signatures
Always validate the webhook signature to ensure authenticity
Handle Retries
Make your endpoint idempotent as webhooks may be sent multiple times
Use HTTPS
Webhook endpoints must use HTTPS for security
Monitor Failures
Set up alerts for webhook delivery failures