Webhooks

Webhooks enable asynchronous notifications for long-running tasks (e.g., conversions >10s), reducing polling overhead. Supported for CMYK, PSD, and DPI APIs; EPS is synchronous.

Setup

• Registration: POST to /v1/webhooks/register with { "url": "https://yourapp.com/waysorted-callback", "events": ["conversion.completed", "conversion.failed"], "secret": "your-hmac-secret" }.
• Verification: Waysorted sends a challenge POST with {"challenge": "token-123"}; echo back in response body.

Events:

• job.started: { "job_id": "...", "type": "cmyk_convert" }
• job.completed: { "job_id": "...", "download_url": "...", "credits_consumed": 10 }
• job.failed: { "job_id": "...", "error": "GhostscriptTimeout" }

Security:

• Payloads HMAC-SHA256 signed with your secret (header: X-Webhook-Signature). Verify on receipt.
• Retries: Exponential backoff (up to 5 attempts, 1h window) on 5xx/timeout; idempotent via X-Waysorted-Idempotency-Key.
• Unregister: DELETE /v1/webhooks/{webhook_id}.

Example Payload (Completed):

json
{
  "event": "job.completed",
  "timestamp": "2025-10-30T12:00:00Z",
  "data": {
    "job_id": "cmyk-job-uuid-456",
    "result": { "download_url": "https://...", "status": "success" }
  },
  "signature": "sha256=abc123..."
}

Handling in Node.js:

javascript
app.post('/waysorted-callback', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);
  const expected = crypto.createHmac('sha256', SECRET).update(payload).digest('hex');
  if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    // Process event
    res.status(200).send('OK');
  } else {
    res.status(401).send('Invalid signature');
  }
});

Last updated: December 2025. Need help? Contact [email protected] or submit feedback via Report a Bug.