Customer Webhooks and Event Delivery
Signed, scoped HTTPS delivery from the transactional PDFHQ event outbox: subscribe, rotate, replay, unsubscribe. Disabled by default until staging acceptance.
Durable event model and gating#
PDFHQ captures selected PDF, AI and signing state transitions in the same database transaction as the state change. A separate worker fans out scoped events and signs metadata-only HTTPS POSTs. Features are disabled unless PDFHQ_CUSTOMER_WEBHOOKS_ENABLED=true and the operator provisions a durable encryption key and scheduled worker. This is source implementation, not a production delivery SLA.
Project ownership is resolved from an x-api-key belonging to HQTools. Browser-only jobs are not automatically broadcast to other projects. Event types: pdf.job.succeeded, pdf.job.failed, ai.job.succeeded, ai.job.failed, signature.sent, signature.viewed, signature.declined, signature.archived, signature.voided, integration.test. Archived means the signed output was verified and stored; sent/viewed do not imply finished signing.
# 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'Delivery retries, rotation and privacy#
Events are delivered at least once; receivers must deduplicate by event id. Retry temporary network errors, HTTP 408, 429 and 5xx with bounded backoff; HTTP 3xx and most other 4xx are terminal and redirects are never followed. After eight attempts the delivery becomes dead and can be explicitly replayed. View GET /v1/webhooks/deliveries?subscription_id=UUID ; replay via POST /v1/webhooks/deliveries/UUID/replay. Secrets can be rotated with POST /v1/webhooks/UUID/rotate, revealing the new key once. Consumers must install the new key immediately; reconnect the Zap when rotating the signing secret.
Only source type, operation, event id and source id are delivered. PDF bytes, AI answers, signer email, signed URLs and billing secrets are excluded. All delivery destinations must resolve to public HTTPS addresses, validated again at send time with pinned IP and TLS hostname verification. Avoid embedding sensitive query parameters in callback URLs.
Zapier private connector →