Custom Webhook Integration Guide

Last updated:

Overview

The Custom Webhook integration allows you to connect tryMarketr to any platform or custom backend that can accept HTTP webhooks. This is perfect for headless CMS platforms, custom publishing systems, or any service with a REST API.

Prerequisites

  • A webhook endpoint that can receive POST requests
  • Ability to parse JSON payloads
  • HTTPS endpoint (recommended for security)

Setup Guide

Step 1: Create Webhook Endpoint

Create an HTTP endpoint that accepts POST requests. Your endpoint should:

  • Accept application/json content type
  • Return HTTP status 200-299 on success
  • Respond within 30 seconds (timeout limit)
  • Be accessible over HTTPS (recommended)

Example Endpoint (Node.js/Express):

app.post('/webhooks/article', express.json(), (req, res) => {
  const { action, article, timestamp } = req.body;
  
  // Process the article
  console.log(`Received ${action} for article: ${article.title}`);
  
  // Return success
  res.status(200).json({ success: true });
});

Step 2: Generate Webhook Secret (Optional)

For security, generate a random secret key to verify webhook authenticity. This prevents unauthorized webhook calls.

Generate a secure secret:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Step 3: Configure in tryMarketr

  1. In tryMarketr, navigate to Integrations
  2. Click Add Integration
  3. Enter a display name (e.g., "My Custom CMS")
  4. Select Custom Webhook as the platform
  5. Fill in the required fields:
    • Webhook URL: Your endpoint URL (e.g., https://api.mysite.com/webhooks/article)
    • Webhook Secret: Your secret key (optional but recommended)
  6. Click Create Integration
  7. Click Test Connection to send a test webhook

Webhook Payload Format

Request Headers

Content-Type: application/json
X-Webhook-Signature: {hmac_signature}

Payload Structure

{
  "action": "publish" | "update" | "unpublish",
  "article": {
    "id": "uuid",
    "title": "Article Title",
    "content": "<html>...</html>",
    "summary": "Article summary text",
    "hero_image": "https://cdn.example.com/image.jpg",
    "workspace_id": "uuid"
  },
  "timestamp": "2024-10-20T10:30:00Z"
}

Field Descriptions

action

The type of operation: publish, update, or unpublish

article.id

Unique identifier for the article (UUID format)

article.title

The article title

article.content

Full HTML content of the article

article.summary

Brief summary or excerpt (may be null)

article.hero_image

URL to the featured image (may be null)

timestamp

ISO 8601 timestamp of when the webhook was sent

HMAC Signature Verification

If you provided a webhook secret, tryMarketr sends an HMAC-SHA256 signature in the X-Webhook-Signature header. Use this to verify the webhook came from tryMarketr.

Node.js Example

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(JSON.stringify(payload));
  const expectedSignature = hmac.digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

app.post('/webhooks/article', express.json(), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifyWebhookSignature(
    req.body,
    signature,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process webhook...
  res.status(200).json({ success: true });
});

Python Example

import hmac
import hashlib
import json

def verify_signature(payload, signature, secret):
    expected_sig = hmac.new(
        secret.encode(),
        json.dumps(payload).encode(),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, expected_sig)

@app.route('/webhooks/article', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature')
    is_valid = verify_signature(
        request.json,
        signature,
        os.environ['WEBHOOK_SECRET']
    )
    
    if not is_valid:
        return {'error': 'Invalid signature'}, 401
    
    # Process webhook...
    return {'success': True}, 200

Troubleshooting

Error: "Webhook endpoint timeout"

Your endpoint took too long to respond (>30 seconds).

Solution: Process webhooks asynchronously. Accept the webhook, return 200 OK immediately, then process the article in the background.

Error: "Connection refused"

tryMarketr cannot reach your webhook endpoint.

Solution: Ensure your endpoint is publicly accessible. Check firewall rules, DNS settings, and that your server is running. Use HTTPS for production.

Error: "Invalid signature"

HMAC signature verification failed.

Solution: Ensure you're using the exact secret from tryMarketr. Verify you're computing the HMAC over the JSON string payload (not the parsed object). Use timing-safe comparison.

Error: "5xx Server Error"

Your webhook endpoint returned a server error.

Solution: Check your server logs for the error details. Ensure your endpoint can handle the webhook payload structure. Test with example payloads.

Testing Webhooks Locally

Use tools like ngrok to expose local endpoints for testing.

Example: ngrok http 3000 then use the ngrok URL as your webhook endpoint.

Best Practices

Security

  • Always use HTTPS endpoints in production
  • Implement HMAC signature verification
  • Validate payload structure before processing
  • Rate limit webhook endpoints to prevent abuse
  • Log all webhook attempts for debugging

Performance

  • Respond to webhooks quickly (acknowledge immediately)
  • Process article content asynchronously
  • Implement retry logic for failures
  • Use job queues for background processing

Reliability

  • Make webhook processing idempotent (safe to retry)
  • Store article IDs to detect duplicates
  • Handle partial failures gracefully
  • Monitor webhook delivery success rates

Example Use Cases

Headless CMS

Publish to Contentful, Strapi, or other headless CMS platforms via their APIs.

Custom Backend

Store articles in your own database and serve them through your custom application.

Static Site Generators

Trigger builds in Netlify, Vercel, or other platforms when new content is published.

Multi-Platform Publishing

Create a webhook endpoint that fans out to multiple platforms simultaneously.

Content Transformations

Apply custom transformations, add metadata, or enrich content before publishing.