Logo PDFHQ

Documents

DocumentationAutomatisation et intégrations

Webhooks clients et livraison d'événements

Livraison HTTPS signée et délimitée à partir de la boîte de réception d'événements transactionnels PDFHQ : abonnez-vous, renouvelez, relisez, désabonnez-vous. Désactivé par défaut jusqu'à l'acceptation de la mise en scène.

Clés API côté serveur Importations de stockage signées

Modèle d'événement durable et gating#

PDFHQ capture le PDF sélectionné, l'IA et les transitions d'état de signature dans la même transaction de base de données que le changement d'état. Un worker distinct distribue les événements délimités et signe les POSTs HTTPS contenant uniquement les métadonnées. Les fonctionnalités sont désactivées sauf si PDFHQ_CUSTOMER_WEBHOOKS_ENABLED=true et l'opérateur provisionne une clé de chiffrement durable et un worker planifié. Ceci est une implémentation source, pas un SLA de livraison en production.

La propriété du projet est résolue à partir d'un x-api-key appartenant à HQTools. Les tâches du navigateur uniquement ne sont pas automatiquement diffusées vers d'autres projets. Types d'événements : pdf.job.succeeded, pdf.job.failed, ai.job.succeeded, ai.job.failed, signature.sent, signature.viewed, signature.declined, signature.archived, signature.voided, integration.test. Archivé signifie que la sortie signée a été vérifiée et stockée ; envoyé/consulté n'implique pas la fin de la signature.

S'abonner, vérifier et révoquer
# 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'

Tentatives de livraison, rotation et confidentialité#

Les événements sont livrés au moins une fois ; les destinataires doivent dédupliquer par ID d'événement. Réessayez les erreurs réseau temporaires, HTTP 408, 429 et 5xx avec un backoff limité ; HTTP 3xx et la plupart des autres 4xx sont terminaux et les redirections ne sont jamais suivies. Après huit tentatives, la livraison devient inactive et peut être rejouée explicitement. Afficher GET /v1/webhooks/deliveries?subscription_id=UUID ; relire via POST /v1/webhooks/deliveries/UUID/replay. Les secrets peuvent être renouvelés avec POST /v1/webhooks/UUID/rotate, révélant la nouvelle clé une seule fois. Les consommateurs doivent installer la nouvelle clé immédiatement ; reconnectez le Zap lors de la rotation du secret de signature.

Seuls le type de source, l'opération, l'ID d'événement et l'ID de source sont livrés. Les octets PDF, les réponses IA, l'e-mail du signataire, les URL signées et les secrets de facturation sont exclus. Toutes les destinations de livraison doivent se résoudre en adresses HTTPS publiques, validées à nouveau au moment de l'envoi avec vérification IP épinglée et vérification du nom d'hôte TLS. Évitez d'intégrer des paramètres de requête sensibles dans les URL de rappel.

Connecteur privé Zapier →
Logo PDFHQ

Outils PDF et intelligence documentaire. Préparez, comprenez et travaillez avec vos documents.

© 2026 PDFHQ. Tous droits réservés.