Klant-webhooks en gebeurtenislevering
Ondertekende, scoped HTTPS-levering vanuit de transactionele PDFHQ-gebeurtenisoutbox: abonneer, roteer, herhaal, meld af. Standaard uitgeschakeld totdat staging-acceptatie.
Duurzaam gebeurtenismodel en gating#
PDFHQ legt geselecteerde PDF, AI en ondertekeningsstatus-overgangen in dezelfde databasetransactie vast als de statuswijziging. Een aparte worker verspreidt scoped events en ondertekent metadata-only HTTPS POSTs. Functies zijn uitgeschakeld tenzij PDFHQ_CUSTOMER_WEBHOOKS_ENABLED=true en de operator voorziet in een duurzame versleutelingssleutel en geplande worker. Dit is bronimplementatie, geen SLA voor productielevering.
Projecteigendom wordt opgelost uit een x-api-key behorend tot HQTools. Browser-only jobs worden niet automatisch naar andere projecten uitgezonden. Gebeurtenistypen: pdf.job.succeeded, pdf.job.failed, ai.job.succeeded, ai.job.failed, signature.sent, signature.viewed, signature.declined, signature.archived, signature.voided, integration.test. Gearchiveerd betekent dat de ondertekende uitvoer is geverifieerd en opgeslagen; verzonden/bekeken betekenen niet dat ondertekening is voltooid.
# 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'Afleveringsherhalingen, rotatie en privacy#
Gebeurtenissen worden minstens eenmaal bezorgd; ontvangers moeten dedupliceren op basis van event-id. Probeer tijdelijke netwerkfouten, HTTP 408, 429 en 5xx opnieuw met begrensd backoff; HTTP 3xx en de meeste andere 4xx zijn definitief en omleidingen worden nooit gevolgd. Na acht pogingen wordt de bezorging dood en kan deze expliciet opnieuw worden afgespeeld. Bekijk GET /v1/webhooks/deliveries?subscription_id=UUID ; opnieuw afspelen via POST /v1/webhooks/deliveries/UUID/replay. Geheimen kunnen worden geroteerd met POST /v1/webhooks/UUID/rotate, waarbij de nieuwe sleutel eenmaal wordt onthuld. Consumenten moeten de nieuwe sleutel onmiddellijk installeren; verbind de Zap opnieuw wanneer je het ondertekeningsgeheim roteert.
Alleen brontype, bewerking, gebeurtenis-id en bron-id worden geleverd. PDF-bytes, AI-antwoorden, e-mailadres ondertekenaar, ondertekende URL's en factureringsgeheimen zijn uitgesloten. Alle afleveringsbestemmingen moeten worden omgezet in openbare HTTPS-adressen, opnieuw gevalideerd op verzendtijd met vastgezette IP en TLS-hostnaamverificatie. Vermijd het insluiten van gevoelige queryparameters in callback-URL's.
Zapier privéconnector →