Webhook Integration Documentation

Learn how to integrate Repostra with your custom webhook endpoint to receive and publish blog posts automatically.

How It Works

When you configure a webhook account in Repostra, we will send HTTP POST requests to your specified webhook URL whenever content is ready to be published. The webhook payload contains all the necessary information to create or update blog posts in your system.

Webhook Payload Format

Repostra sends webhook requests in JSON format. The payload structure depends on the content type:

Blog Post Format

When posting blog content, the payload uses the following format:

{
  "type": "blog_post",
  "title": "Your Blog Post Title",
  "content": "<h2>Heading</h2>\n<p>Paragraph content...</p>",
  "repostra_post_id": 123,
  "excerpt": "Optional excerpt text",
  "featured_image_url": "https://example.com/image.jpg"
}

Social Post Format

When posting social media content, the payload uses this format:

{
  "type": "social_post",
  "platform": "website",
  "content_type": "text",
  "content": "Post content in HTML format",
  "topic": "Post topic/title",
  "scheduled_for": "2025-11-27T12:00:00Z",
  "blog_content_id": 123,
  "image_url": "https://example.com/image.jpg"
}

Content Format

The content field contains HTML-formatted text that preserves all formatting including:

• Headings (H1-H6)
• Paragraphs
• Lists (ordered and unordered)
• Blockquotes
• Images
• Tables

HMAC Signature Verification (Optional)

For enhanced security, you can enable HMAC-SHA256 signature verification. When enabled, Repostra will sign each webhook payload and include the signature in the X-Repostra-Signature header.

How to Enable Signing

1. In your Repostra account, go to Social Accounts
2. Create or edit a Website account with "Webhook" as the posting method
3. Enter your webhook URL
4. Optionally, enter a Signing Secret in the "Signing Secret" field
5. Save the account

Verifying the Signature

To verify the signature on your end, follow these steps:

// 1. Get the raw request body
$rawBody = file_get_contents('php://input');

// 2. Get the signature from the header
$signature = $_SERVER['HTTP_X_REPOSTRA_SIGNATURE'] ?? '';

// 3. Get your signing secret (stored securely)
$signingSecret = 'your-signing-secret';

// 4. Calculate the expected signature
$expectedSignature = hash_hmac('sha256', $rawBody, $signingSecret);

// 5. Compare signatures (use hash_equals to prevent timing attacks)
if (!hash_equals($expectedSignature, $signature)) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

// 6. Process the webhook if signature is valid
$data = json_decode($rawBody, true);
// ... process your webhook

Example: Node.js/Express

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

app.use(express.raw({ type: 'application/json' }));

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-repostra-signature'];
  const signingSecret = process.env.REPOSTRA_SIGNING_SECRET;
  
  const expectedSignature = crypto
    .createHmac('sha256', signingSecret)
    .update(req.body)
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  const data = JSON.parse(req.body);
  // Process webhook...
  res.json({ success: true });
});

Example: Python/Flask

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Repostra-Signature')
    signing_secret = os.environ.get('REPOSTRA_SIGNING_SECRET')
    
    expected_signature = hmac.new(
        signing_secret.encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()
    
    if not hmac.compare_digest(signature, expected_signature):
        return jsonify({'error': 'Invalid signature'}), 401
    
    data = request.get_json()
    # Process webhook...
    return jsonify({'success': True})

Response Format

Your webhook endpoint should return a JSON response. For successful processing:

{
  "success": true,
  "post_id": 456,
  "message": "Post created successfully"
}

For errors, return an appropriate HTTP status code (400, 401, 500, etc.) with an error message:

{
  "error": "error_type",
  "message": "Human-readable error message"
}

Testing Your Webhook

You can test your webhook integration directly from the Repostra interface:

1. Go to Social Accounts in your Repostra dashboard
2. Find your webhook account in the list
3. Click the Test button next to the account
4. Check your webhook endpoint logs to verify the test payload was received

The test will send a sample payload to your webhook URL so you can verify your endpoint is working correctly before publishing actual content.

Security Best Practices

• Always use HTTPS for your webhook URL to encrypt data in transit
• Enable signature verification to ensure requests are from Repostra
• Store your signing secret securely (environment variables, secret management services)
• Validate the payload before processing to ensure data integrity
• Implement rate limiting to prevent abuse
• Log webhook events for debugging and auditing

Need Help?

If you need assistance with webhook integration, please visit our support page at repostra.app.