Integration Guide
Webhook Integration
Connect your website or custom CMS with SEO Ladders using our webhook integration. Receive articles directly to your server as soon as they're generated.
Setting Up Your Webhook
Webhook URL
The HTTPS endpoint where you want to receive article data. Must be publicly accessible.
HTTP Method
POST (default) or PUT. Choose based on your API design and how you handle incoming articles.
Secret Token
Auto-generated token to verify requests are from SEO Ladders. Sent as the X-Webhook-Secret header.
Include HTML
Option to receive HTML-formatted content alongside Markdown. Enable if your CMS uses HTML.
Implementing Webhook Secret Verification
Always verify the X-Webhook-Secret header to ensure requests are genuinely from SEO Ladders. Here are examples in popular languages:
server.js
const express = require('express');
const app = express();
// Store your secret token securely (e.g., environment variable)
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
function validateWebhookSecret(req) {
const receivedSecret = req.headers['x-webhook-secret'];
return receivedSecret === WEBHOOK_SECRET;
}
app.post('/webhook/seo-ladders', express.json(), (req, res) => {
// Verify the request is from SEO Ladders
if (!validateWebhookSecret(req)) {
return res.status(401).json({ error: 'Invalid webhook secret' });
}
// Process the webhook payload
const { title, content_markdown, slug, meta_description } = req.body;
console.log('Received article:', title);
// Your logic here: save to database, trigger build, etc.
res.status(200).json({ message: 'Webhook processed successfully' });
});
app.listen(3000, () => {
console.log('Webhook server running on port 3000');
});Publish Articles Event
When an article is published, we send a POST request to your webhook endpoint with the following payload:
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the article |
title | string | The article title |
slug | string | URL-friendly version of the title |
meta_description | string | SEO meta description |
content_markdown | string | Article content in Markdown format |
content_html | string | Article content in HTML format (if enabled) |
keyword | string | Target SEO keyword |
article_type | string | Type of article (e.g., "Explainer", "Guide: How-to", "Listicle") |
word_count | number | Total word count |
reading_time | number | Estimated reading time in minutes |
featured_image | object | Featured image data (url, alt) |
json_ld | object | Structured data for SEO |
created_at | string | Creation timestamp (ISO 8601) |
generated_at | string | Generation timestamp (ISO 8601) |
Example Payload
payload.json
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": "How to Implement Webhooks",
"slug": "how-to-implement-webhooks",
"meta_description": "Learn how to implement webhooks in your application with this comprehensive guide.",
"content_markdown": "# How to Implement Webhooks\n\nWebhooks are powerful...",
"content_html": "<h1>How to Implement Webhooks</h1><p>Webhooks are powerful...</p>",
"keyword": "implement webhooks",
"article_type": "Guide: How-to",
"word_count": 1847,
"reading_time": 9,
"featured_image": {
"url": "https://storage.example.com/images/webhook-guide.jpg",
"alt": "How to Implement Webhooks"
},
"json_ld": {
"@context": "https://schema.org",
"@type": "Article",
"headline": "How to Implement Webhooks"
},
"created_at": "2026-01-31T12:00:00.000Z",
"generated_at": "2026-01-31T14:30:00.000Z"
}Testing Your Webhook
- 1Navigate to Settings > CMS Integration in your dashboard
- 2Select "Custom Webhook" as your CMS type
- 3Enter your webhook endpoint URL
- 4Copy the auto-generated Secret Token
- 5Click Test Connection to verify connectivity
- 6Publish an article to test the full flow
- 7Check your server logs to verify the webhook was received
Best Practices
- Always verify the X-Webhook-Secret header to ensure requests are genuine
- Implement proper error handling and logging in your webhook receiver
- Set up monitoring for your webhook endpoint to ensure it's always available
- Consider implementing a retry mechanism for failed webhook deliveries
- Use HTTPS for your webhook endpoint (required in production)
- Respond quickly (within 30 seconds) to avoid timeout errors
- Store received articles idempotently using the id field to prevent duplicates
SEO Implementation Guide
The webhook payload includes SEO-optimized fields. Here's how to use them to maximize your search engine visibility:
| Field | How to Use | SEO Benefit |
|---|---|---|
featured_image | Place at the top of your article content | Increases engagement, improves social sharing, and helps with image search rankings |
json_ld | Inject as <script type="application/ld+json"> in <head> or end of <body> | Enables rich snippets in Google (star ratings, FAQ dropdowns, article info). Can increase CTR by 20-30% |
meta_description | Set as <meta name="description"> in your <head> | Controls the snippet shown in search results. Well-written descriptions improve click-through rates |
slug | Use as the URL path for the article | Clean, keyword-rich URLs are easier to read and can improve rankings |
Example Implementation
seo-helpers.js
function buildArticleHtml(payload) {
let html = '';
// 1. Featured Image at the top (improves engagement & SEO)
if (payload.featured_image?.url) {
html += '<figure class="featured-image">' +
'<img src="' + payload.featured_image.url + '" ' +
'alt="' + (payload.featured_image.alt || payload.title) + '" />' +
'</figure>\n\n';
}
// 2. Article content
html += payload.content_html || convertMarkdownToHtml(payload.content_markdown);
// 3. JSON-LD structured data at the end
if (payload.json_ld) {
html += '\n\n<script type="application/ld+json">\n' +
JSON.stringify(payload.json_ld, null, 2) +
'\n</script>';
}
return html;
}
// For your HTML <head> section:
function buildMetaTags(payload) {
return '<meta name="description" content="' + payload.meta_description + '" />' +
'<meta property="og:title" content="' + payload.title + '" />' +
'<meta property="og:description" content="' + payload.meta_description + '" />' +
'<meta property="og:image" content="' + (payload.featured_image?.url || '') + '" />';
}Why This Matters
- JSON-LD structured data enables rich snippets in Google (FAQ dropdowns, article info, star ratings) which can increase click-through rates by 20-30%.
- Featured images at the top of content improve user engagement and are used for social media previews and Google Discover.
- Meta descriptions control how your article appears in search results, directly impacting whether users click.
Troubleshooting
Ready to Get Started?
Set up your webhook integration in minutes and start receiving AI-generated articles directly to your platform.