Logo PDFHQ

Documenti

DocumentazioneAutomazione e integrazioni

Webhook cliente e consegna degli eventi

Consegna HTTPS firmata e scoped dalla casella di posta degli eventi transazionali PDFHQ: sottoscrivi, ruota, riproduci, annulla l'iscrizione. Disabilitato per impostazione predefinita fino all'accettazione della staging.

Chiavi API lato server Caricamenti di archiviazione firmati

Modello di evento durevole e gating#

PDFHQ acquisisce il PDF selezionato, l'IA e le transizioni di stato della firma nella stessa transazione del database del cambio di stato. Un worker separato distribuisce gli eventi con ambito e firma i POST HTTPS solo metadati. Le funzioni sono disabilitate a meno che PDFHQ_CUSTOMER_WEBHOOKS_ENABLED=true e l'operatore fornisce una chiave di crittografia durevole e un worker programmato. Questa è implementazione sorgente, non un SLA di consegna in produzione.

La proprietà del progetto è risolta da un x-api-key appartenente a HQTools. I job solo browser non vengono trasmessi automaticamente ad altri progetti. Tipi di evento: pdf.job.succeeded, pdf.job.failed, ai.job.succeeded, ai.job.failed, signature.sent, signature.viewed, signature.declined, signature.archived, signature.voided, integration.test. Archiviato significa che l'output firmato è stato verificato e archiviato; inviato/visualizzato non implicano firma completata.

Sottoscrivi, verifica e revoca
# 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'

Tentativi di consegna, rotazione e privacy#

Gli eventi vengono consegnati almeno una volta; i ricevitori devono deduplicare per ID evento. Riprova gli errori di rete temporanei, HTTP 408, 429 e 5xx con backoff limitato; HTTP 3xx e la maggior parte degli altri 4xx sono terminali e i reindirizzamenti non vengono mai seguiti. Dopo otto tentativi la consegna diventa non recapitabile e può essere riprodotta esplicitamente. Visualizza GET /v1/webhooks/deliveries?subscription_id=UUID ; riproduci tramite POST /v1/webhooks/deliveries/UUID/replay. I segreti possono essere ruotati con POST /v1/webhooks/UUID/rotate, rivelando la nuova chiave una sola volta. I consumatori devono installare immediatamente la nuova chiave; riconnettere lo Zap quando si ruota il segreto di firma.

Solo il tipo di origine, l'operazione, l'ID evento e l'ID origine vengono consegnati. I byte PDF, le risposte AI, l'email del firmatario, gli URL firmati e i segreti di fatturazione sono esclusi. Tutte le destinazioni di consegna devono risolvere a indirizzi HTTPS pubblici, convalidati di nuovo al momento dell'invio con verifica IP bloccato e nome host TLS. Evita di incorporare parametri di query sensibili negli URL di callback.

Connettore privato Zapier →
Logo PDFHQ

Strumenti PDF e intelligenza documentale. Prepara, comprendi e lavora con i tuoi documenti.

© 2026 PDFHQ. Tutti i diritti riservati.