Async & Webhooks

Für große PDFs, vollständige Seiten-Screenshots oder hohes Volumen rendern Sie asynchron: enqueuen Sie den Job, erhalten Sie sofort eine ID zurück und rufen Sie dann ab oder erhalten Sie einen signierten Webhook.

# Enqueue

Fügen Sie async: true (oder eine webhookUrl oder eine notifyEmail) zu einer beliebigen render- oder screenshot-Anfrage hinzu. Geben Sie webhookUrl für einen signierten Callback an, notifyEmail, um per E-Mail benachrichtigt zu werden, wenn der Job abgeschlossen ist, oder weder noch und rufen Sie einfach ab:

bash

curl https://api.mostlyrender.com/v1/renders \
  -H "Authorization: Bearer mr_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "tpl_abc",
    "output": "pdf",
    "async": true,
    "webhookUrl": "https://your.app/hooks/mostlyrender"
  }'

json

{ "id": "job_xyz789", "status": "queued" }

Die Antwort ist 202 Accepted mit einer Job-ID.

# Poll

bash

curl https://api.mostlyrender.com/v1/renders/job_xyz789 \
  -H "Authorization: Bearer mr_live_…"

json

{
  "id": "job_xyz789",
  "status": "done",
  "kind": "render",
  "result": { "id": "rnd_abc", "url": "https://img.mostlyrender.com/…/rnd_abc.pdf", "output": "pdf" },
  "error": null
}

status bewegt sich queued → processing → done (oder error). Wenn done, enthält result das Render-Objekt { id, url, output }.

python

job = mr.render_async("tpl_abc", output="pdf", webhook_url="https://your.app/hooks/mostlyrender")
final = mr.wait_for_render(job["id"])
print(final["result"]["url"])

# Webhooks

Wenn Sie eine webhookUrl übergeben, POSTet MostlyRender das Job-Ergebnis dorthin, wenn es abgeschlossen ist:

json

{
  "id": "job_xyz789",
  "status": "done",
  "result": { "id": "rnd_abc", "url": "https://img.mostlyrender.com/…/rnd_abc.pdf", "output": "pdf" }
}

# Überprüfen Sie die Signatur

Jeder Webhook enthält eine HMAC-SHA256-Signatur des Raw Body im Header x-mostlyrender-signature, mit dem Präfix sha256=. Berechnen Sie ihn mit Ihrem Signing Secret neu und vergleichen Sie in konstanter Zeit:

import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Antworten Sie mit beliebigen 2xx, um zu bestätigen. Die Zustellung wird bei Fehlern ein paar Mal wiederholt; Webhook-Ziele sind wie Screenshot-URLs gegen SSRF geschützt.