Back to Documentation
Webhook Event Types
Complete reference of all webhook events you can subscribe to in Ranklite.
Event Structure
All webhook events follow this consistent structure:
{
"id": "evt_1234567890", // Unique event identifier
"type": "article.published", // Event type
"created": 1734134400, // Unix timestamp
"data": {
// Event-specific payload
}
}Available Events
article.created
Triggered when a new article is generated or created
Example Payload
{
"id": "evt_1234567890",
"type": "article.created",
"created": 1734134400,
"data": {
"article": {
"id": "art_abc123",
"title": "Your Article Title",
"status": "draft",
"created_at": "2025-12-14T10:00:00Z",
"word_count": 2500
}
}
}article.published
Triggered when an article is published to your website
Example Payload
{
"id": "evt_1234567890",
"type": "article.published",
"created": 1734134400,
"data": {
"article": {
"id": "art_abc123",
"title": "Your Article Title",
"url": "https://example.com/article",
"status": "published",
"published_at": "2025-12-14T10:00:00Z",
"word_count": 2500
}
}
}article.updated
Triggered when an existing article is modified
Example Payload
{
"id": "evt_1234567890",
"type": "article.updated",
"created": 1734134400,
"data": {
"article": {
"id": "art_abc123",
"title": "Updated Article Title",
"status": "published",
"updated_at": "2025-12-14T11:30:00Z",
"changes": [
"title",
"content"
]
}
}
}article.deleted
Triggered when an article is deleted from the system
Example Payload
{
"id": "evt_1234567890",
"type": "article.deleted",
"created": 1734134400,
"data": {
"article": {
"id": "art_abc123",
"title": "Deleted Article",
"deleted_at": "2025-12-14T12:00:00Z"
}
}
}article.scheduled
Triggered when an article is scheduled for future publication
Example Payload
{
"id": "evt_1234567890",
"type": "article.scheduled",
"created": 1734134400,
"data": {
"article": {
"id": "art_abc123",
"title": "Scheduled Article",
"status": "scheduled",
"scheduled_for": "2025-12-15T09:00:00Z"
}
}
}article.failed
Triggered when article generation or publishing fails
Example Payload
{
"id": "evt_1234567890",
"type": "article.failed",
"created": 1734134400,
"data": {
"article": {
"id": "art_abc123",
"title": "Failed Article",
"status": "failed",
"error": "Publishing failed: Connection timeout",
"failed_at": "2025-12-14T10:30:00Z"
}
}
}Event Filtering
When creating a webhook, you can subscribe to specific events or all events. To filter events:
- 1. Go to Settings → Webhooks
- 2. Edit your webhook
- 3. Select the events you want to receive
- 4. Save your changes
Handling Events
Example of handling multiple event types in your webhook endpoint:
app.post('/api/webhooks/ranklite', async (req, res) => {
const { type, data } = req.body;
switch (type) {
case 'article.created':
// Handle new article
await handleNewArticle(data.article);
break;
case 'article.published':
// Send notification
await sendNotification(`Article published: ${data.article.title}`);
break;
case 'article.updated':
// Sync with external system
await syncArticle(data.article);
break;
case 'article.failed':
// Alert team
await alertTeam(data.article.error);
break;
default:
console.log(`Unhandled event type: ${type}`);
}
res.status(200).send('OK');
});Event Delivery
- Order: Events are delivered in the order they occur
- Retry: Failed deliveries are retried up to 3 times with exponential backoff
- Timeout: Your endpoint must respond within 5 seconds
- Idempotency: Use the event ID to handle duplicate deliveries