Webhooks
Webhooks permitem que sistemas se comuniquem em tempo real, enviando notificações ou dados entre aplicações quando eventos específicos ocorrem. Atualmente está habilitado o envio de webhooks para alterações de status de Envelopes, ou seja, sempre quando o status de um envelope mudar, o sistema irá realizar uma chamada POST para cada um dos webhooks criados e ativos na organização a qual o Envelope pertence.
Configurando webhooks
Para cadastrar um webhook na sua conta, entre em contato com o suporte e tenha em mãos o endereço de sua api, o qual receberá os eventos de webhooks e a organização desejada vinculada a sua conta. Com isso em mãos, iremos cadastrar um webhook com a url fornecida e a partir desse momento qualquer alteração de status de envelopes na sua organização vai gerar um disparo de evento de webhook.
Eventos de Envelopes
Rascunho - draft: Status no qual o envelope é criado, mas não iniciado. Pode ser retomado a qualquer momento para ser editado e enviado.
Enviado - in-transit: Status no qual a criação do envelope é concluída com sucesso, o envelope então dispara suas notificações e passa a aguardar as ações de assinatura, aprovação, rejeição e cancelamento.
Expirado - expired: Status no qual o envelope passou da data de validade definida e já não aceita mais ações por parte dos assinantes e aprovadores. Este é um status final do envelope.
Falhou - halted: Status no qual o envelope passou por algum tipo de erro durante o processo de assinatura e/ou aprovação e falhou. Este é um status final do envelope.
Finalizado - completed: Status no qual o envelope foi completamente assinado e aprovado por todas as partes. Neste estágio, o envelope não aceita mais edições ou retroagir para algum outro status anterior. Este é um status final do envelope.
Cancelado - cancelled: Status no qual o envelope foi cancelado por parte de quem criou ou com uma ação de rejeição por parte de qualquer um dos destinatários. Este é um status final do envelope.
Estrutura do webhook
Após o webhook ativo, sempre que houver mudança no status de algum envelope em sua organização, será disparada uma requisição, conforme exemplo abaixo:
{
"uuid": "9e98b7cb-9cf6-43ac-b4f8-2745017039ac",
"created_at": "2025-04-04 17:25:57",
"event_type": "envelope.status.completed",
"summary": "Envelope completed",
"resource_type": "envelope",
"resource": {
"uuid": "9e9872e8-2585-4f85-961b-b9020daf283f",
"created_at": "2025-04-04 14:13:20",
"updated_at": "2025-04-04 17:25:55",
"status": "completed"
},
"event_version": "1.0",
"resource_version": "1.0"
}
Note que dentro do campo "resource" estão presentes os dados do recurso em questão (no caso do exemplo "envelope", veja o campo "resource_type"). Os campos dentro do objeto "resource" se referem ao recurso em questão, já os campos fora do objeto "resource" se referem ao evento em questão.
Autenticação e segurança
Ao criar um webhook será gerada uma chave "secret" que deverá ser guardada em sua aplicação para posteriormente ao receber uma requisição via webhook, ser comparada e validada. A validação ocorre da seguinte forma:
No cabeçalho da requisição enviada pelo webhook, irá conter um campo chamado signature, caso queira (recomendamos) que faça a validação do valor contido nesse campo para confirmar que o disparo foi efetuado de uma de nossas APIs.
Para fazer isso, faça o json_encode do payload recebido, e logo em seguida gere um hash_hmac sha256 juntando o payload e o secret gerado na etapa de cadastro do webhook, o valor gerado após esse processo deverá ser exatamente igual ao campo "signature" enviado no cabeçalho da requisição.
Ex.:
$payloadJson = json_encode($payload);
$signature = hash_hmac('sha256', $payloadJson, $secret);
Reenvio em caso de falha
Ao enviar um evento de webhook o sistema irá analisar a resposta obtida pelo sistema de destino, caso seja algo diferente de sucesso (diferente de 2xx), ele irá tentar reenviar o mesmo evento mais 2 vezes, com um intervalo de 10 segundos e 100 segundos respectivamente.