Sealsimple
Começar grátis

Webhooks: enviar eventos de documentos para o seu sistema

Um webhook envia uma mensagem JSON assinada ao seu URL quando um documento é enviado, aberto, assinado, concluído, recusado, expirado ou cancelado. Requer Pro e um proprietário ou administrador.

Esta tradução é anterior ao artigo em inglês, por isso alguns detalhes podem ter mudado. Ler a versão em inglês

Um webhook envia uma mensagem para um URL seu sempre que acontece algo a um documento, para que o seu próprio sistema possa reagir. Os webhooks fazem parte do Pro: funcionam num espaço de trabalho enquanto um dos seus proprietários tiver o Pro, e só os proprietários e administradores os podem gerir. Cada espaço de trabalho tem os seus.

Adicionar um webhook

  1. Abra Definições e marca no menu da conta e vá a Integrações.
  2. Prima Adicionar webhook.
  3. Introduza o URL do endpoint. Tem de começar por https:// e ser público: os endereços de redes privadas, os próprios endereços do Sealsimple e os URLs com nome de utilizador e palavra-passe são recusados.
  4. Se quiser, adicione um Nome, escolha os Eventos (de início, estão todos assinalados) e prima Adicionar webhook.
  5. Copie a Chave de assinatura que aparece e prima Enviar evento de teste.

Um espaço de trabalho pode ter até 10 webhooks.

Eventos

  • document.sent: Documento enviado
  • document.viewed: Aberto por um destinatário, uma vez por destinatário
  • document.signed: Assinado por um signatário, uma vez por signatário
  • document.completed: Concluído: todos assinaram
  • document.declined: Recusado
  • document.expired: Expirado
  • document.canceled: Cancelado

O que enviamos

Um POST com um corpo JSON: id (igual em todas as tentativas, para poder ignorar duplicados), event, created_at, workspace_id, um document com id, title, status e url e, nos eventos sobre uma pessoa, um recipient com name, email e role. Um documento cancelado tem o estado voided. O PDF assinado em si não é enviado. O evento de teste tem o evento test e um documento e um signatário fictícios.

Verificar a assinatura

Cada pedido tem um cabeçalho Sealsimple-Signature como t=1700000000,v1=…, além de Sealsimple-Event e Sealsimple-Delivery. Para a verificar:

  1. Pegue no corpo bruto do pedido, exatamente como chegou.
  2. Leia t (uma hora Unix em segundos) e v1 do cabeçalho.
  3. Calcule o HMAC-SHA256 de t, de um ponto e do corpo, com a sua chave de assinatura completa como chave, em hexadecimal minúsculo.
  4. Aceite o pedido só se o resultado for igual a v1 (compare em tempo constante) e se t não tiver mais do que alguns minutos.

Em Como ligar, Verificar a assinatura (Node.js) mostra isto em código, com Copiar código. Nova chave substitui a chave de imediato, por isso atualize a sua verificação logo a seguir.

Novas tentativas, o registo e a pausa

Responda com um estado 2xx no prazo de 10 segundos. Caso contrário, tentamos novamente mais tarde, até 6 tentativas no total, ao longo de cerca de um dia. Os redirecionamentos não são seguidos, e uma resposta 410 interrompe as tentativas. O Registo de entregas mostra as últimas 50 mensagens com a resposta do seu endpoint, e Reenviar envia uma novamente.

Após 20 entregas falhadas seguidas, pomos o webhook em pausa (Em pausa após falhas) e enviamos um e-mail aos proprietários do espaço de trabalho. Corrija o endpoint, volte a ativar o webhook e reenvie o que precisar a partir do registo. Também pode pôr um webhook em pausa com o respetivo interruptor: os eventos que acontecem enquanto está em pausa não são enviados mais tarde. Sem o Pro, os webhooks ficam, mas não enviam nada.

Este artigo foi útil?

Experimente com o seu próximo contrato.

5 envios grátis em cada mês civil. Sem cartão de crédito.

Ainda precisa de ajuda?

Pergunte ao nosso assistente no chat: responde de imediato. Ou envie-nos um e-mail e uma pessoa responde-lhe num dia útil.