PDFHQ-logo

Documenten

DocumentatieAutomatisering en integraties

Klant-webhooks en gebeurtenislevering

Ondertekende, scoped HTTPS-levering vanuit de transactionele PDFHQ-gebeurtenisoutbox: abonneer, roteer, herhaal, meld af. Standaard uitgeschakeld totdat staging-acceptatie.

Server-side API-sleutels Ondertekende opslagupload

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.

Abonneer je, verifieer en intrekken
# 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 →
PDFHQ-logo

PDF-tools en documentintelligentie. Bereid, begrijp en werk met uw documenten.

© 2026 PDFHQ. Alle rechten voorbehouden.