Um webhook é um aviso automático. Você cadastra uma URL do seu sistema e escolhe um evento. Quando o evento acontece numa operação, a ForSign envia os dados para essa URL. Assim o seu sistema não precisa perguntar à API de tempos em tempos se algo mudou. O uso mais comum é saber a hora certa de baixar o documento assinado.
Quando usar
- Baixar o PDF final assim que ele estiver pronto.
- Atualizar o status do contrato no seu ERP ou CRM quando alguém assina.
- Receber as respostas do formulário assim que o participante preenche.
- Saber quando um participante envia os anexos pedidos.
Cadastrar o webhook
-
No menu, clique em Desenvolvedor, abra a aba Configurações e desça até a seção Webhooks. Clique em Adicionar Webhook.
A seção Webhooks fica em Configurações, abaixo da Chave da API. O botão Adicionar Webhook abre o cadastro. Ver a tela inteira -
Em Nome, dê um nome que identifique o uso. Em URL do Webhook, informe o endereço do seu sistema que vai receber os avisos. Use HTTPS.
Dê um nome ao webhook e informe a URL do seu sistema que vai receber os avisos. Ver a tela inteira -
Em Tipos de Eventos, escolha o evento. Se o seu sistema pede um cabeçalho fixo, como um token próprio, clique em Adicionar em Cabeçalhos e preencha Chave e Valor. Clique em Salvar.
Escolha o tipo de evento e, se o seu sistema pedir, inclua cabeçalhos com Chave e Valor. Ver a tela inteira -
A janela Secret do Webhook mostra o secret uma única vez. Copie e guarde num cofre de segredos. O seu sistema usa esse secret para conferir que o aviso veio mesmo da ForSign.
Ao salvar, a tela mostra o secret do webhook uma única vez. Copie e guarde. Ver a tela inteira -
Clique em Fechar. O webhook entra na lista com nome, URL, tipo de evento e status Ativo.
O webhook entra na lista com nome, URL, tipo de evento e status. Ver a tela inteira
Para receber mais de um evento na mesma URL, cadastre um webhook para cada evento.
Eventos disponíveis
| Evento na tela | Quando dispara |
|---|---|
| Atualização de Operação | A operação muda de situação. |
| Documento Assinado | Um participante assina. |
| Operação Finalizada | A operação é concluída. |
| Documento Pronto para Download | O PDF final assinado está pronto para baixar. |
| Anexos Enviados | Um participante envia um anexo. |
| Todos os Anexos Enviados | O participante envia todos os anexos pedidos e avança. |
| Formulário Preenchido | Um participante preenche o formulário. |
| Crédito Consumido | Um crédito do plano é consumido. |
| Crédito Estornado | Um crédito volta ao plano, por cancelamento ou expiração da operação. |
Para baixar o documento assinado, use Documento Pronto para Download. Ele só dispara quando o arquivo final já existe.
Conferir os envios
-
Na aba Logs do Painel do desenvolvedor, cada envio aparece com a data, a URL e o código de status que o seu sistema respondeu.
A aba Logs lista cada envio, com data, URL e o código de status que o seu sistema respondeu. Ver a tela inteira -
Clique num envio para abrir Detalhes do Log, com o payload enviado e a resposta recebida. Os botões de cópia ajudam a testar no seu sistema.
Detalhes do Log mostra o código de status, a URL, o payload enviado e a resposta recebida. Ver a tela inteira -
Para enviar de novo, selecione os envios na lista e use a ação de reenvio.
Como o seu sistema confere o aviso
Cada envio traz dois cabeçalhos: X-ForSign-Signature, com a assinatura HMAC-SHA256 do corpo calculada com o secret, e X-ForSign-Timestamp. O seu sistema calcula a mesma assinatura com o secret guardado e compara. A janela do secret mostra um exemplo de verificação. Os cabeçalhos que você cadastrou também vão em todo envio.
O que acontece depois
- Se o seu sistema não responder com sucesso, a ForSign tenta de novo algumas vezes. Veja os prazos em Eventos do webhook e novas tentativas.
- Um webhook que falha seguidamente por muito tempo é suspenso, e os responsáveis pela integração recebem um aviso. Depois de corrigir o seu sistema, reative o webhook pelo menu da linha.
Limites e detalhes
- Responda rápido, com um código de sucesso, e processe os dados depois. O envio espera no máximo 30 segundos.
- O mesmo aviso pode chegar mais de uma vez. Trate repetições pelo ID da operação e pelo tipo de evento.
- Os logs ficam disponíveis por 90 dias.
- Para cadastrar webhooks e ver os logs, o seu perfil precisa da permissão de gerenciar integrações.
- Webhooks não consomem crédito.
Perguntas comuns
Perdi o secret. E agora? Abra o menu da linha do webhook e gere um secret novo. Atualize o secret no seu sistema.
Como pauso um webhook sem apagar? Use a opção de ativar e desativar no menu da linha. O webhook inativo não recebe avisos.
Posso testar antes de ligar o meu sistema? Sim. Cadastre a URL de um serviço de teste de webhooks, conclua uma operação de teste e veja o envio na aba Logs.