Webhooks de Cliente e Entrega de Eventos
Entrega HTTPS assinada e com escopo da caixa de saída de eventos transacionais PDFHQ: inscrever-se, girar, reproduzir, cancelar inscrição. Desabilitado por padrão até aceitação de preparação.
Modelo de evento durável e gating#
PDFHQ captura o PDF selecionado, IA e transições de estado de assinatura na mesma transação de banco de dados que a mudança de estado. Um worker separado distribui eventos com escopo e assina POSTs HTTPS apenas de metadados. Os recursos são desabilitados a menos que PDFHQ_CUSTOMER_WEBHOOKS_ENABLED=true e o operador provisiona uma chave de encriptação durável e um worker agendado. Esta é implementação de origem, não um SLA de entrega de produção.
A propriedade do projeto é resolvida de um x-api-key pertencente ao HQTools. Trabalhos apenas no navegador não são automaticamente transmitidos para outros projetos. Tipos de 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. Arquivado significa que a saída assinada foi verificada e armazenada; enviado/visualizado não implicam assinatura concluída.
# 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'Tentativas de entrega, rotação e privacidade#
Os eventos são entregues pelo menos uma vez; os receptores devem desduplicar por ID de evento. Tente novamente erros temporários de rede, HTTP 408, 429 e 5xx com backoff limitado; HTTP 3xx e a maioria dos outros 4xx são terminais e redirecionamentos nunca são seguidos. Após oito tentativas, a entrega se torna inativa e pode ser reproduzida explicitamente. Visualizar GET /v1/webhooks/deliveries?subscription_id=UUID ; reproduzir via POST /v1/webhooks/deliveries/UUID/replay. Segredos podem ser rotacionados com POST /v1/webhooks/UUID/rotate, revelando a nova chave uma vez. Os consumidores devem instalar a nova chave imediatamente; reconecte o Zap ao girar o segredo de assinatura.
Apenas tipo de fonte, operação, ID de evento e ID de fonte são entregues. Bytes de PDF, respostas de IA, email do signatário, URLs assinadas e segredos de faturamento são excluídos. Todos os destinos de entrega devem resolver para endereços HTTPS públicos, validados novamente no momento do envio com verificação de IP fixado e nome de host TLS. Evite incorporar parâmetros de consulta sensíveis em URLs de retorno de chamada.
Conector privado Zapier →