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 when a new article is successfully published to our distribution network.

article.updated

Fired when an existing article is modified and republished.

article.deleted

Fired when an article is removed.

Payload Format

Webhooks are sent as a POST request with a JSON body.

json

{
  "event": "article.published",
  "timestamp": "2024-03-15T10:00:00Z",
  "data": {
    "id": "art_123",
    "title": "Dog Training Tips",
    "slug": "dog-training-tips",
    "status": "published",
    "html": "<p className="leading-loose">...</p>"
  }
}

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