Integrations Guide

1. Overview

MockReview webhooks allow you to receive real-time notifications about events in your projects. Connect to Slack, Discord, JIRA, or build custom integrations with your own systems.

2. JIRA Integration

Automatically sync design review updates to your JIRA issues. When files are approved, rejected, or commented on, MockReview posts formatted comments directly to linked JIRA issues.

Quick Start

1. Create a JIRA API token at Atlassian Account Security
2. In MockReview, go to Settings → Webhooks
3. Create a new webhook and select "JIRA" platform
4. Enter your JIRA API URL (e.g., https://yoursite.atlassian.net/rest/api/3/issue/PROJECT-123/comment)
5. Add Authorization header with Base64-encoded credentials
6. Enable "Format for JIRA" to use Atlassian Document Format

3. Slack Setup

Step 1: Create Incoming Webhook

1. Go to https://api.slack.com/apps
2. Click "Create New App" → "From scratch"
3. Name your app "MockReview" and select your workspace
4. Navigate to "Incoming Webhooks" and activate
5. Click "Add New Webhook to Workspace"
6. Select the channel to post to (e.g., #design-reviews)
7. Copy the generated webhook URL (starts with https://hooks.slack.com/services/...)

Step 2: Add to MockReview

1. In MockReview, go to Settings → Integrations
2. Click "Create Webhook"
3. Select "Slack" as platform
4. Paste your webhook URL
5. Give it a name (e.g., "#design-reviews")
6. Select the events you want to receive
7. Click "Test" to verify, then "Save"

🎨 Review Requested: Homepage Redesign
Project: Mobile App Q4

View Review → [Link]
3 files • 2 reviewers invited

4. Discord Setup

Step 1: Create Discord Webhook

1. Open Discord and navigate to your server
2. Right-click the channel where you want notifications
3. Click "Edit Channel" → "Integrations"
4. Click "Create Webhook"
5. Customize the name and avatar (optional)
6. Click "Copy Webhook URL"

Step 2: Add to MockReview

1. In MockReview, go to Settings → Integrations
2. Click "Create Webhook"
3. Select "Discord" as platform
4. Paste your webhook URL
5. Give it a name (e.g., "Design Reviews Channel")
6. Select the events you want to receive
7. Click "Test" to verify, then "Save"

┌─────────────────────────────────────
│ 💬 Comment Added
│ Project: Mobile App Q4
│ Review: Homepage Redesign
│ File: hero-section.png
│
│ "The call-to-action button needs 
│  more contrast"
│ - john@example.com
│
│ [View Comment]
└─────────────────────────────────────

5. Custom Webhooks

Custom webhooks allow you to integrate MockReview with any system that can receive HTTP POST requests.

Requirements

• HTTPS endpoint (HTTP not supported for security)
• Must accept POST requests with JSON body
• Should respond with 2xx status code
• Timeout: 10 seconds

Setup

1. Create an HTTPS endpoint in your application
2. In MockReview, go to Settings → Integrations
3. Click "Create Webhook"
4. Select "Custom" as platform
5. Enter your endpoint URL
6. Optional: Provide a signing secret for HMAC verification
7. Select events and save

5.1 HMAC Signature Verification

For security, custom webhooks include an HMAC signature in the X-MockReview-Signature header.

const crypto = require('crypto');

function verifyWebhook(req, secret) {
  const signature = req.headers['x-mockreview-signature'];
  const body = JSON.stringify(req.body);
  
  const hmac = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  
  return signature === hmac;
}

// Express.js example
app.post('/webhooks/mockreview', (req, res) => {
  if (!verifyWebhook(req, 'your-secret-here')) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = req.body;
  console.log('Received:', event.eventType);
  
  res.status(200).send('OK');
});

import hmac
import hashlib
from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks/mockreview', methods=['POST'])
def webhook():
    signature = request.headers.get('X-MockReview-Signature')
    body = request.get_data()
    secret = 'your-secret-here'
    
    expected = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    
    if signature != expected:
        return 'Invalid signature', 401
    
    event = request.get_json()
    print(f"Received: {event['eventType']}")
    
    return 'OK', 200

6. Webhook Events

7. Payload Examples

{
  "attachments": [
    {
      "color": "#4299e1",
      "title": "🎨 Review Requested: Homepage Redesign",
      "title_link": "https://mockreview.com/projects/123/review-requests/456",
      "fields": [
        {
          "title": "Project",
          "value": "Mobile App Q4",
          "short": true
        },
        {
          "title": "Reviewers",
          "value": "john@example.com, sarah@example.com",
          "short": true
        },
        {
          "title": "Files",
          "value": "3 files uploaded",
          "short": true
        }
      ],
      "footer": "MockReview",
      "ts": 1729468800
    }
  ]
}

8. Security Best Practices

• Always use HTTPS: Never expose webhook endpoints over plain HTTP
• Verify signatures: For custom webhooks, always validate the HMAC signature
• Use strong secrets: Generate random, long signing secrets (32+ characters)
• Validate payload: Check that received data matches expected structure
• Rate limiting: Implement rate limiting on your webhook endpoint
• Rotate secrets: Periodically update your webhook signing secrets
• Monitor failures: Track failed deliveries and investigate anomalies
• Keep URLs private: Don't share webhook URLs publicly or commit to version control

9. Troubleshooting

Webhook not delivering

• Use the "Test" button in MockReview to verify connectivity
• Check that your endpoint is publicly accessible via HTTPS
• Verify your server is responding with 2xx status codes
• Check server logs for errors or timeout issues
• Ensure firewall/security groups allow incoming connections

Slack messages not appearing

• Verify webhook URL is still valid (URLs can expire)
• Check you selected the correct channel when creating the webhook
• Regenerate webhook in Slack if URL is old
• Ensure the MockReview app has permission to post

Discord embeds not showing

• Confirm webhook URL is correct and not deleted in Discord
• Check channel permissions allow webhook posting
• Verify embeds are enabled in user settings (User Settings → Text & Images → Show embeds)

Signature verification failing

• Ensure you're using the exact secret from MockReview settings
• Hash the raw request body before JSON parsing
• Check character encoding (should be UTF-8)
• Verify you're using HMAC SHA-256 algorithm
• Compare signatures as strings, not hex vs base64