Webhooks

Receive real-time notifications when validations complete.

Overview

Webhooks allow you to receive HTTP callbacks when validation jobs complete. This is useful for automated workflows and CI/CD pipelines.

Note: Webhooks are available on Starter, Pro, and Enterprise plans.

Configuration

You can configure your webhook URL in two ways:

Set a default webhook URL in your account settings
Include a webhook_url in the validation request options

Request with Webhook

curl -X POST https://meshqa.vercel.app/api/v1/validate \
  -H "Authorization: Bearer mqk_your_api_key" \
  -F "file=@model.glb" \
  -F 'options={"webhook_url": "https://your-server.com/webhook"}'

Payload

When a validation completes, we'll send a POST request to your webhook URL:

{
  "event": "validation.completed",
  "job_id": "val_abc123def456",
  "result": {
    "valid": true,
    "health_score": 87,
    "grade": "excellent",
    "meshes": [...],
    "securityScan": {
      "safe": true,
      "scannedFiles": 1,
      "warnings": []
    }
  }
}

Signature Verification

Each webhook request includes an HMAC-SHA256 signature in theX-MeshQA-Signature header. Verify this signature to ensure the request came from MeshQA.

Node.js Verification

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-meshqa-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook...
  res.status(200).send('OK');
});

Retry Policy

If your webhook endpoint returns an error (non-2xx status code), we'll retry the delivery with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failed attempts, the webhook delivery is abandoned.

Best Practices

Return a 200 response quickly, then process asynchronously
Always verify the signature before processing
Handle duplicate deliveries (use job_id for idempotency)
Use HTTPS for your webhook endpoint
Set up alerting for webhook failures