Webhooks

Os webhooks permitem que seu aplicativo receba notificações de eventos em tempo real do PDFSimple. Em vez de consultar a API repetidamente para verificar o status de uma tarefa, registre um endpoint e o PDFSimple enviará um payload assinado via POST quando um evento ocorrer.

Configurando um webhook

1. Vá para Painel → Webhooks e clique em Adicionar endpoint.
2. Insira a URL do seu endpoint HTTPS (por exemplo, https://yourapp.com/webhooks/pdfsimple).
3. Selecione os eventos que deseja receber (por exemplo, job.completed, job.failed).
4. Clique em Criar. Um segredo de webhook exclusivo é exibido — copie-o imediatamente, ele é exibido apenas uma vez.
5. Armazene o segredo com segurança nas variáveis de ambiente do seu aplicativo.

Eventos de webhook

• job.completed — uma tarefa de processamento de PDF foi concluída com sucesso. O payload inclui o ID da tarefa, a URL do arquivo de saída e metadados.
• job.failed — uma tarefa encontrou um erro. O payload inclui a mensagem de erro.

Verificando assinaturas de webhook

Toda requisição de webhook inclui um cabeçalho X-PDFSimple-Signature contendo uma assinatura HMAC-SHA256 do corpo bruto da requisição, calculada usando seu segredo de webhook. Sempre verifique essa assinatura antes de processar o payload.

const crypto = require('crypto');

function verifySignature(rawBody, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Novas tentativas e garantias de entrega

Se o seu endpoint não retornar uma resposta 2xx em até 30 segundos, o PDFSimple tentará novamente a entrega com backoff exponencial, até 5 tentativas ao longo de 30 dias. Os eventos de webhook são retidos por 30 dias.