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
Nesta página
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
- Abra Definições e marca no menu da conta e vá a Integrações.
- Prima Adicionar webhook.
- 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. - Se quiser, adicione um Nome, escolha os Eventos (de início, estão todos assinalados) e prima Adicionar webhook.
- 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 enviadodocument.viewed: Aberto por um destinatário, uma vez por destinatáriodocument.signed: Assinado por um signatário, uma vez por signatáriodocument.completed: Concluído: todos assinaramdocument.declined: Recusadodocument.expired: Expiradodocument.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:
- Pegue no corpo bruto do pedido, exatamente como chegou.
- Leia
t(uma hora Unix em segundos) ev1do cabeçalho. - 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. - Aceite o pedido só se o resultado for igual a
v1(compare em tempo constante) e setnã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.