A ForSign envia um POST para a URL do seu webhook sempre que acontece o evento que você escolheu, como um documento assinado ou o PDF final pronto. Se o seu servidor não responder com sucesso, a ForSign faz mais 3 tentativas: depois de 30 segundos, de 2 minutos e de 10 minutos.
Os eventos
Cada webhook escuta um tipo de evento. Para receber vários eventos na mesma URL, cadastre um webhook para cada tipo.
| Evento na tela | Nome técnico | Quando dispara |
|---|---|---|
| Atualização de Operação | UpdateOperation |
A operação muda de situação. |
| Documento Assinado | DocumentSigned |
Um participante assina. |
| Operação Finalizada | CompletedOperation |
A operação é concluída. |
| Documento Pronto para Download | DocumentReady |
O PDF final assinado está pronto para baixar. |
| Anexos Enviados | AttachmentFilled |
O participante envia um anexo. |
| Todos os Anexos Enviados | AllAttachmentsFilled |
O participante termina todos os anexos exigidos. Dispara uma vez. |
| Formulário Preenchido | FormFilled |
O participante preenche o formulário. |
| Crédito Consumido | CreditConsumed |
Um crédito do plano é consumido. |
| Crédito Estornado | CreditRefunded |
Um crédito volta ao plano, por cancelamento ou expiração da operação. |
Para baixar o documento assinado, espere o DocumentReady. O CompletedOperation chega antes do arquivo final estar pronto.
O que vem no corpo
O corpo é um JSON com os campos em PascalCase: Action, ActionDescription, Success, Message, CreatedAt, CompanyId, OperationId, OperationMemberId e Data.
- Nos eventos da operação,
Datatraz a operação:Id,ExternalId,Status,Stage,Members,FileseMetadata. - Nos eventos do participante,
Datatraz o participante, com anexos, campos de formulário e resultados do antifraude. - Os campos do formulário só vêm preenchidos no evento
FormFilled. - Nos eventos de crédito, os dados do movimento vêm no campo
Credit, não emData.
Como conferir que veio da ForSign
Ao cadastrar o webhook, o app mostra o Secret do Webhook uma única vez. Com ele, cada entrega traz dois cabeçalhos:
X-ForSign-Signature:sha256=seguido do HMAC-SHA256 do corpo, calculado com o secret.X-ForSign-Timestamp: o horário do envio, em segundos Unix.
Calcule o HMAC do corpo exatamente como chegou e compare com o cabeçalho. Se o secret vazar, use Regenerar Secret. O secret antigo deixa de valer na hora.
Os cabeçalhos que você cadastrou no webhook também vão em toda entrega.
Novas tentativas
A ForSign espera até 30 segundos pela resposta. Qualquer resposta fora da faixa 2xx, ou o tempo esgotado, conta como falha.
| Entrega | Espera | Tempo desde o evento |
|---|---|---|
| 1ª (original) | imediato | |
| 2ª | 30 s | 30 s |
| 3ª | 2 min | 2 min 30 s |
| 4ª | 10 min | 12 min 30 s |
Depois da 4ª entrega sem sucesso, a ForSign desiste daquele evento. Você ainda pode mandar de novo pela aba Logs do Painel do desenvolvedor, com o botão Reenviar.
Suspensão automática
Se um webhook acumula 10 eventos abandonados seguidos, e já se passaram 24 horas desde a primeira falha da sequência, a ForSign suspende o webhook. Uma entrega com sucesso no meio zera a contagem.
Quando isso acontece:
- O webhook aparece como Suspenso na lista.
- Quem tem permissão de gerenciar integrações recebe um e-mail e um aviso na central de notificações.
- O webhook só volta a receber eventos depois de Reativar, no menu de três pontos da linha. Antes, confira se a sua URL está no ar.
Boas práticas
- Responda 2xx rápido e processe o evento depois, em segundo plano.
- Trate entregas repetidas. Um timeout do seu lado seguido de nova tentativa pode entregar o mesmo evento duas vezes. Use
Data.IdmaisActionpara descartar repetidos. - Use o
ExternalIdda operação para achar o registro no seu sistema.
Perguntas comuns
Perdi eventos enquanto meu servidor estava fora. Como recupero? Abra a aba Logs, filtre pelo período e pelo status de erro e use Reenviar nos eventos que faltaram.
Um webhook pode escutar mais de um evento? Não. Cada webhook é uma URL mais um tipo de evento. Cadastre um por tipo, mesmo que a URL seja a mesma.
O webhook consome crédito? Não. As entregas e os reenvios não gastam crédito.