Kunden-Webhooks und Ereignisbereitstellung
Signierte, begrenzte HTTPS-Lieferung aus der transaktionalen PDFHQ-Event-Outbox: abonnieren, rotieren, wiedergeben, abmelden. Standardmäßig deaktiviert bis zur Staging-Akzeptanz.
Dauerhaftes Ereignismodell und Gating#
PDFHQ erfasst ausgewählte PDF-, KI- und Signing-Zustandsübergänge in derselben Datenbanktransaktion wie die Zustandsänderung. Ein separater Worker verteilt scoped Events und signiert Metadata-only HTTPS POSTs. Features sind deaktiviert, sofern nicht PDFHQ_CUSTOMER_WEBHOOKS_ENABLED=true und der Anbieter stellt einen dauerhaften Verschlüsselungsschlüssel und einen geplanten Worker bereit. Dies ist eine Referenzimplementierung, keine produktive Lieferungs-SLA.
Die Projekteigentümerschaft wird von einem aufgelöst x-api-key gehört zu HQTools. Browser-only-Jobs werden nicht automatisch an andere Projekte übertragen. Ereignistypen: pdf.job.succeeded, pdf.job.failed, ai.job.succeeded, ai.job.failed, signature.sent, signature.viewed, signature.declined, signature.archived, signature.voided, integration.test. Archiviert bedeutet, dass die signierte Ausgabe überprüft und gespeichert wurde; gesendet/angesehen bedeuten nicht zwingend abgeschlossenes Signieren.
# API key must be held in a server-side secret store.
curl -X POST 'https://api.pdfhq.io/v1/webhooks' \
-H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
-d '{"target_url":"https://customer.example.com/pdfhq/events","events":["pdf.job.succeeded","ai.job.succeeded"]}'
# Save the returned secret once: verify HMAC SHA-256 over timestamp + "." + exact JSON bytes.
# Headers: X-PDFHQ-Webhook-Id, X-PDFHQ-Webhook-Timestamp, X-PDFHQ-Webhook-Signature: v1=hex
# Reject payloads older than 300 seconds. Dedupe on event id.
curl -X DELETE 'https://api.pdfhq.io/v1/webhooks/SUBSCRIPTION_UUID' -H 'x-api-key: YOUR_API_KEY'Zustellungswiederholungen, Rotation und Datenschutz#
Ereignisse werden mindestens einmal zugestellt; Empfänger müssen nach Ereignis-ID deduplizieren. Wiederhole temporäre Netzwerkfehler, HTTP 408, 429 und 5xx mit begrenztem Backoff; HTTP 3xx und die meisten anderen 4xx sind endgültig und Umleitungen werden nie befolgt. Nach acht Versuchen wird die Zustellung inaktiv und kann explizit wiedergegeben werden. Ansicht GET /v1/webhooks/deliveries?subscription_id=UUID ; Wiederholung über POST /v1/webhooks/deliveries/UUID/replay. Secrets können mit rotiert werden POST /v1/webhooks/UUID/rotate, wobei der neue Schlüssel einmal offengelegt wird. Verbraucher müssen den neuen Schlüssel sofort installieren; verbinde den Zap erneut, wenn du das Signierungsgeheimnis rotierst.
Nur Quelltyp, Operation, Event-ID und Quell-ID werden übermittelt. PDF-Bytes, KI-Antworten, E-Mail des Unterzeichners, signierte URLs und Abrechnungsgeheimnisse sind ausgeschlossen. Alle Lieferziele müssen zu öffentlichen HTTPS-Adressen aufgelöst werden, die zum Sendezeitpunkt erneut mit angehefteter IP und TLS-Hostname-Verifizierung validiert werden. Vermeiden Sie das Einbetten sensibler Abfrageparameter in Callback-URLs.
Zapier Private Connector →