Webhook Pelanggan dan Pengiriman Acara
Pengiriman HTTPS yang ditandatangani dan dibatasi dari kotak keluar acara transaksional PDFHQ: berlangganan, putar, putar ulang, berhenti berlangganan. Dinonaktifkan secara default hingga penerimaan pementasan.
Model acara tahan lama dan gating#
PDFHQ menangkap PDF yang dipilih, AI dan transisi status penandatanganan dalam transaksi database yang sama dengan perubahan status. Pekerja terpisah mengirimkan acara berskop dan menandatangani HTTPS POST hanya metadata. Fitur dinonaktifkan kecuali PDFHQ_CUSTOMER_WEBHOOKS_ENABLED=true dan operator menyediakan kunci enkripsi yang tahan lama dan pekerja terjadwal. Ini adalah implementasi sumber, bukan SLA pengiriman produksi.
Kepemilikan proyek diselesaikan dari x-api-key milik HQTools. Pekerjaan hanya-browser tidak secara otomatis disiarkan ke proyek lain. Jenis acara: pdf.job.succeeded, pdf.job.failed, ai.job.succeeded, ai.job.failed, signature.sent, signature.viewed, signature.declined, signature.archived, signature.voided, integration.test. Diarsipkan berarti output yang ditandatangani diverifikasi dan disimpan; dikirim/dilihat tidak menyiratkan penandatanganan selesai.
# 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'Pengiriman ulang, rotasi, dan privasi#
Acara disampaikan minimal sekali; penerima harus menghilangkan duplikat berdasarkan id acara. Coba lagi kesalahan jaringan sementara, HTTP 408, 429 dan 5xx dengan backoff terbatas; HTTP 3xx dan sebagian besar 4xx lainnya bersifat terminal dan pengalihan tidak pernah diikuti. Setelah delapan percobaan, pengiriman menjadi mati dan dapat diputar ulang secara eksplisit. Lihat GET /v1/webhooks/deliveries?subscription_id=UUID ; putar ulang melalui POST /v1/webhooks/deliveries/UUID/replay. Rahasia dapat dirotasi dengan POST /v1/webhooks/UUID/rotate, mengungkapkan kunci baru sekali. Konsumen harus memasang kunci baru segera; sambungkan kembali Zap saat memutar rahasia penandatanganan.
Hanya jenis sumber, operasi, id acara dan id sumber yang dikirimkan. Byte PDF, jawaban AI, email penandatangan, URL yang ditandatangani dan rahasia penagihan dikecualikan. Semua tujuan pengiriman harus diselesaikan ke alamat HTTPS publik, divalidasi lagi pada waktu pengiriman dengan verifikasi IP tertanam dan nama host TLS. Hindari menyematkan parameter kueri sensitif dalam URL callback.
Konektor pribadi Zapier →