API Webhook Integration

Setup Requirements

• Integration Name: 2-30 characters, letters/numbers/spaces only.
• Webhook Endpoint: Public HTTPS URL to receive webhooks.
• Access Token: Secret token we will send as Authorization: Bearer <token>.

Security

We authenticate requests by including your Access Token in the Authorization header. Your handler should reject requests that do not include a valid token.

// Node.js/Express example
app.use(express.json());

const ACCESS_TOKEN = process.env.ACCESS_TOKEN;

function validateAccessToken(req) {
  const authHeader = req.headers.authorization || '';
  return authHeader.startsWith('Bearer ') && authHeader.split(' ')[1] === ACCESS_TOKEN;
}

app.post('/webhook', (req, res) => {
  if (!validateAccessToken(req)) {
    return res.status(401).json({ error: 'Invalid access token' });
  }
  // Handle payload
  res.status(200).json({ ok: true });
});

Event: publish_articles

When you publish an article, we send the following JSON payload:

{
  "event_type": "publish_articles",
  "timestamp": "2023-04-01T12:00:00Z",
  "data": {
    "articles": [
      {
        "id": "123456",
        "title": "How to Implement Webhooks",
        "content_markdown": "Webhooks are a powerful...",
        "content_html": "<p>Webhooks are a powerful...</p>",
        "meta_description": "Learn how to implement webhooks in your application",
        "created_at": "2023-03-31T10:30:00Z",
        "image_url": "https://example.com/images/webhook-article.jpg",
        "slug": "how-to-implement-webhooks",
        "tags": ["webhooks", "integration", "api"]
      }
    ]
  }
}

Testing

1. Go to Dashboard → Integrations → Add Integration → API Webhook.
2. Enter your endpoint and access token, then click Test Your Webhook.
3. Publish an article to trigger a real publish_articles event.

Best Practices

• Always validate the Bearer token.
• Respond with HTTP 200 as soon as possible; process asynchronously if needed.
• Log errors and consider retries on your side for robustness.