Receber eventos do Drime Sign com webhooks

Com um webhook, o Drime chama o seu servidor sempre que algo acontece com as suas solicitações de assinatura. Cada chamada é um POST em JSON, assinado com um segredo para que o seu servidor possa verificar que ela vem do Drime.

#Adicionar um webhook

1. Abra Configurações > Desenvolvedores > Webhooks.

   No Drime Sign, você também pode clicar em Preferências, abrir a aba Webhooks e depois clicar em Abrir as configurações de Desenvolvedores.

2. Clique em Adicionar um webhook.

3. Em URL do endpoint, digite o endereço do servidor que vai receber as chamadas.

4. Em Eventos, coloque em Ativado cada evento que você quer receber e clique em Criar o webhook.

   A mensagem Webhook criado confirma a criação.

5. Copie o segredo agora e clique em Pronto.

   Segredo do webhook, copie agora: ele só é exibido uma vez. Guarde-o em um lugar seguro.

#Os eventos

#O que o Drime envia

Cada chamada traz estes cabeçalhos:

• X-Drime-Event: o evento, por exemplo envelope.completed;

• X-Drime-Delivery: o número da entrega;

• X-Drime-Signature: sha256= seguido do HMAC SHA-256 do corpo bruto, calculado com o seu segredo.

O corpo JSON contém event_type, event_uuid, timestamp e data, que traz o documento em questão com os signatários dele. A seção Webhooks mostra um exemplo completo em Exemplo de requisição e verificação de assinatura.

Uma mesma entrega pode chegar mais de uma vez: use event_uuid para processar cada evento uma única vez.

#Verificar a assinatura

Calcule o HMAC SHA-256 do corpo bruto da requisição com o seu segredo e compare o resultado com o cabeçalho X-Drime-Signature. Por exemplo, em Node.js:

import crypto from 'node:crypto';

function isFromDrime(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return header.length === expected.length && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Use o corpo exatamente como ele foi recebido, antes de fazer o parse do JSON.

#Testar e acompanhar as entregas

• Enviar um teste envia um evento de teste: Evento de teste na fila, confira o log de entregas.

• Entregas lista cada chamada com o status dela: Sucesso, Pendente ou Falhou. Reenviar envia uma entrega de novo.

• Se o seu servidor não responder ou responder com um erro, o Drime tenta de novo, em até 10 tentativas ao longo de cerca de 34 horas.

• A chave Ativado / Desativado pausa um webhook sem excluí-lo: Webhook pausado confirma a pausa, e Webhook ativado, a reativação.

#Trocar o segredo ou excluir o webhook

• Trocar o segredo cria um novo segredo. O app avisa: Trocar o segredo? Seu segredo atual para de funcionar na hora. Atualize o seu servidor imediatamente.

• Excluir remove o webhook: Excluir este webhook e todo o histórico de entregas dele?

#Se não funcionar

#Próximos passos

• Criar um aplicativo ou conectar webhooks

• Criar um token de API

• O que contém o certificado de auditoria de um documento assinado