Configuração de webhooks

Visão geral

Webhooks são chamadas HTTP disparadas por eventos na KivoSign. Quando um evento acontece (por exemplo, um documento é assinado), a KivoSign envia um HTTP POST para a URL configurada com os detalhes do evento.

Usos comuns:

• Sincronizar o status dos documentos com o seu banco de dados
• Disparar fluxos automáticos quando documentos são assinados
• Integrar com CRM ou outros sistemas
• Enviar notificações personalizadas às partes interessadas

Criando um endpoint de webhook

Antes de configurar o webhook na KivoSign, você precisa de um endpoint que receba requisições HTTP POST. Um exemplo mínimo:

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/kivosign', (req, res) => {
  const { event, payload, createdAt } = req.body;

  console.log(`Evento recebido: ${event}`);
  console.log(`ID do documento: ${payload.id}`);
  console.log(`Título do documento: ${payload.title}`);

  switch (event) {
    case 'DOCUMENT_COMPLETED':
      // Trata o documento concluído
      break;
    case 'DOCUMENT_SIGNED':
      // Trata a assinatura
      break;
  }

  // Responde 200 OK para confirmar o recebimento
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Servidor de webhooks na porta 3000');
});

Configurando webhooks no painel da KivoSign

Requisitos da URL do webhook

O endpoint precisa atender a estes requisitos:

Escolhendo os eventos

Ao criar o webhook, você pode assinar um ou mais eventos:

Você pode assinar todos os eventos ou só os que precisa. Por exemplo, se só quer saber quando os documentos estão totalmente assinados, assine apenas DOCUMENT_COMPLETED.

Veja Eventos de webhook para o payload de cada tipo de evento.

Testando webhooks

A KivoSign tem um teste embutido para confirmar que seu endpoint funciona.

O payload de teste usa dados de exemplo realistas, para você conferir se o endpoint processa os eventos corretamente. Depois de enviar, a resposta aparece nos logs de chamadas do webhook.

Vendo os logs do webhook

Cada webhook guarda um log de todas as tentativas de entrega. Para ver:

Reenviando webhooks com falha

Se uma entrega falhar, você pode reenviá-la manualmente:

Política de novas tentativas

A entrega falha quando o endpoint responde com status diferente de 2xx, quando o prazo de 10 segundos acaba ou quando a requisição não se completa. Redirecionamentos não são seguidos, então respostas 3xx também contam como falha. Falhas de rede e URLs bloqueadas são registradas com código de resposta 0.

A KivoSign faz algumas novas tentativas automáticas. Só a entrega específica é marcada como falha: o webhook não é desativado, então os próximos eventos continuam sendo entregues. Depois que as tentativas automáticas acabam, você pode reenviar a entrega manualmente pelo painel.

Boas práticas de segurança

Próximos passos

• Eventos de webhook - O payload de cada tipo de evento
• Verificação de webhooks - Proteja seus webhooks verificando o segredo