Webhook Integration

Setting Up Your Webhook

To set up a webhook integration, you'll need to provide the following information:

• Integration Name: A unique name for your webhook integration (2-30 characters, no special characters).
• Webhook Endpoint: The URL where you want to receive webhook events (must be a valid HTTPS URL).
• Access Token: A secret key used to verify the authenticity of incoming webhook requests.

Implementing Webhook Secret Mechanism

To ensure the security of your webhook, we use a secret token to sign the payload. Here's how to verify incoming webhooks:

const express = require('express');
const app = express();

// This should be securely stored, e.g., in environment variables
const ACCESS_TOKEN = 'your_secure_access_token';

function validateAccessToken(req) {
  const authHeader = req.headers.authorization;
  if (!authHeader || !authHeader.startsWith("Bearer ")) {
    return false;
  }
  const token = authHeader.split(" ")[1];
  return token === ACCESS_TOKEN;
}

app.use(express.json());

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

  // Process the webhook payload here
  // ...

  res.status(200).json({ message: 'Webhook processed successfully' });
});

app.listen(3000, () => console.log('Webhook server listening on port 3000'));

Publish Articles Event

When an article is published, we'll send a POST request to your webhook endpoint with a JSON payload. The payload will include:

• event_type: The type of event that occurred ( always "publish_articles" in this case).
• timestamp: The time the event occurred (ISO 8601 format).
• data: An object containing event-specific data, including an array of affected articles.

Article Data Properties

Each article in the payload will contain the following properties:

• id: Unique identifier for the article.
• title: The title of the article.
• content_markdown: The article content in Markdown format.
• content_html: The article content in HTML format.
• meta_description: A brief description of the article for SEO purposes.
• created_at: The timestamp when the article was created (ISO 8601 format).
• image_url: The URL of the main image associated with the article.
• slug: The URL-friendly version of the article title used for permalinks.
• tags: An array of tags associated with the article.

{
  "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"]
      },
      {
        "id": "789012",
        "title": "Best Practices for API Design",
        "content_markdown": "When designing an API...",
        "content_html": "<p>When designing an API...</p>",
        "meta_description": "Discover the best practices for designing robust APIs",
        "created_at": "2023-03-31T11:45:00Z",
        "image_url": "https://example.com/images/api-design-article.jpg",
        "slug": "best-practices-for-api-design",
        "tags": ["api", "design", "best practices"]
      }
    ]
  }
}

Testing Your Webhook

Once you've set up your webhook integration, you can test it by publishing an article:

1. Navigate to any article page in your dashboard.
2. Click the "Publish" button to publish the article.
3. Your webhook endpoint should receive a POST request with the article data.
4. Check your server logs to verify the webhook was received and processed correctly.

Best Practices

• Always verify the webhook access token to ensure the request is 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.

Troubleshooting