Webhooks Integration | SiteLift Docs

Webhooks are perfect if you have a custom CMS and want to trigger a build process, update a database, or send a Slack notification the moment an article is ready.

Setup Guide

1
Create an Endpoint
Expose a public HTTP POST endpoint on your server capable of receiving JSON payloads.
- Ensure the endpoint can parse application/json.
- It must respond with a 2xx status code within 10 seconds.
2
Register the Webhook in SiteLift
Tell SiteLift where to send the events.
- Navigate to Project Settings > Webhooks in your dashboard.
- Click Add Webhook and paste your endpoint URL.
- Select the events you want to subscribe to.
3
Verify Signatures
Secure your endpoint by validating the X-SiteLift-Signature header using your webhook secret.

Available Events

article.published

Fired the first time an article is published. Create the post on your side.

article.updated

Fired when a published article is edited and republished. The payload is the same as article.published and carries the full updated article. Match it to the existing post by slug (or articleId) and update it in place; the slug never changes.

Payload Format

Webhooks are sent as a POST request with a JSON body. article.published and article.updated share this shape; only event differs.

json

{
  "event": "article.updated",
  "timestamp": "2024-03-15T10:00:00.000Z",
  "data": {
    "articleId": "3f1c…",
    "title": "Dog Training Tips",
    "slug": "dog-training-tips",
    "contentHtml": "<p>…</p>",
    "contentMarkdown": "…",
    "seoMeta": { "title": "…", "description": "…" },
    "schemaMarkup": { "@type": "Article" },
    "featuredImageUrl": "https://…",
    "language": "en",
    "images": [
      { "imageType": "inline", "imageUrl": "https://…", "altText": "…", "caption": null, "placementHint": null, "sortOrder": 0 }
    ]
  }
}

Tip

Treat every event as an upsert keyed on slug. A receiver that creates on article.published and updates on article.updated stays correct even if a delivery is retried.

Security & Verification

To verify that a webhook request actually came from SiteLift (and not a malicious actor), we include an X-SiteLift-Signature header. This is an HMAC SHA-256 signature generated using your webhook secret.

Tip

You can find your Webhook Secret in the SiteLift dashboard under Project Settings > Webhooks.

Here is an example of verifying the signature in a Node.js / Express environment:

server.ts

import crypto from 'crypto';
import express from 'express';

const app = express();
const WEBHOOK_SECRET = process.env.SITELIFT_WEBHOOK_SECRET;

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-sitelift-signature'];
  
  // Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  // Securely compare
  if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
    const payload = JSON.parse(req.body.toString());
    console.log('Valid webhook received:', payload.event);
    res.status(200).send('OK');
  } else {
    res.status(401).send('Invalid signature');
  }
});

Retry Policy

If your server responds with an error code (e.g., 500) or times out (after 10 seconds), SiteLift will attempt to deliver the webhook up to 3 times with exponential backoff. Please ensure your webhook receiver endpoint responds with a 2xx status code promptly.

Webhooks