Webhooks de cliente y entrega de eventos
Entrega HTTPS firmada y limitada desde la bandeja de salida de eventos transaccionales de PDFHQ: suscribirse, rotar, reproducir, desuscribirse. Deshabilitado por defecto hasta la aceptación de staging.
Modelo de evento duradero y control de acceso#
PDFHQ captura el PDF seleccionado, IA y transiciones de estado de firma en la misma transacción de base de datos que el cambio de estado. Un worker separado distribuye eventos con alcance y firma POSTs HTTPS solo de metadatos. Las características están deshabilitadas a menos que PDFHQ_CUSTOMER_WEBHOOKS_ENABLED=true y el operador proporciona una clave de cifrado duradera y un trabajador programado. Esta es la implementación de origen, no un SLA de entrega de producción.
La propiedad del proyecto se resuelve desde un x-api-key pertenecientes a HQTools. Los trabajos solo del navegador no se transmiten automáticamente a otros proyectos. Tipos de eventos: pdf.job.succeeded, pdf.job.failed, ai.job.succeeded, ai.job.failed, signature.sent, signature.viewed, signature.declined, signature.archived, signature.voided, integration.test. Archivado significa que la salida firmada fue verificada y almacenada; enviado/visto no implica firma finalizada.
# 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'Reintentos de entrega, rotación y privacidad#
Los eventos se entregan al menos una vez; los receptores deben deduplicar por id de evento. Reintentar errores de red temporal, HTTP 408, 429 y 5xx con backoff acotado; HTTP 3xx y la mayoría de otros 4xx son terminales y los redireccionamientos nunca se siguen. Después de ocho intentos, la entrega se vuelve inactiva y se puede reproducir explícitamente. Ver GET /v1/webhooks/deliveries?subscription_id=UUID ; reproducir mediante POST /v1/webhooks/deliveries/UUID/replay. Los secretos se pueden rotar con POST /v1/webhooks/UUID/rotate, revelando la nueva clave una sola vez. Los consumidores deben instalar la nueva clave inmediatamente; reconectar el Zap al rotar el secreto de firma.
Solo se entregan el tipo de fuente, operación, ID de evento e ID de fuente. Se excluyen bytes de PDF, respuestas de IA, correo electrónico del firmante, URLs firmadas y secretos de facturación. Todos los destinos de entrega deben resolverse en direcciones HTTPS públicas, validadas nuevamente en el momento del envío con verificación de IP fija y nombre de host TLS. Evita incrustar parámetros de consulta sensibles en URLs de devolución de llamada.
Conector privado de Zapier →