Logo PDFHQ

Documentos

DocumentaçãoAutomação e integrações

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.

Chaves de API do lado do servidor Uploads de armazenamento assinado

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.

Inscrever-se, verificar e revogar
# 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 →
Logo PDFHQ

Ferramentas PDF e inteligência de documentos. Prepare, compreenda e trabalhe com seus documentos.

© 2026 PDFHQ. Todos os direitos reservados.