Webhooks

Mit Webhooks kann Ihre Anwendung Echtzeit-Ereignisbenachrichtigungen von PDFSimple erhalten. Anstatt die API nach dem Auftragsstatus abzufragen, registrieren Sie einen Endpunkt, und PDFSimple sendet einen signierten Payload per POST, sobald ein Ereignis eintritt.

Einen Webhook einrichten

1. Gehen Sie zu Dashboard → Webhooks und klicken Sie auf Endpunkt hinzufügen.
2. Geben Sie Ihre HTTPS-Endpunkt-URL ein (z. B. https://yourapp.com/webhooks/pdfsimple).
3. Wählen Sie die Ereignisse aus, die Sie erhalten möchten (z. B. job.completed, job.failed).
4. Klicken Sie auf Erstellen. Ein eindeutiges Webhook-Secret wird angezeigt — kopieren Sie es sofort, es wird nur einmal angezeigt.
5. Speichern Sie das Secret sicher in den Umgebungsvariablen Ihrer Anwendung.

Webhook-Ereignisse

• job.completed — ein PDF-Verarbeitungsauftrag wurde erfolgreich abgeschlossen. Der Payload enthält die Auftrags-ID, die URL der Ausgabedatei und Metadaten.
• job.failed — bei einem Auftrag ist ein Fehler aufgetreten. Der Payload enthält die Fehlermeldung.

Webhook-Signaturen überprüfen

Jede Webhook-Anfrage enthält einen X-PDFSimple-Signature-Header mit einer HMAC-SHA256-Signatur des rohen Anfragetexts, berechnet mit Ihrem Webhook-Secret. Überprüfen Sie diese Signatur immer, bevor Sie den Payload verarbeiten.

const crypto = require('crypto');

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

Wiederholungsversuche und Zustellgarantien

Wenn Ihr Endpunkt nicht innerhalb von 30 Sekunden mit einer 2xx-Antwort reagiert, wiederholt PDFSimple die Zustellung mit exponentiellem Backoff, bis zu 5 Versuche über 30 Tage. Webhook-Ereignisse werden 30 Tage lang aufbewahrt.