Webhooks de API
O webhook é o aviso que o CleanFin manda para outro sistema quando algo acontece. Hoje o aviso disponível é o de ★CleanPay - Fatura: cada mudança na situação de uma fatura CleanPay (quando ela é paga, por exemplo) é enviada para o endereço que você cadastrar.
O endereço que recebe o aviso fica no sistema do outro lado, e quem o prepara é o programador dele. Aqui você só cadastra esse endereço. Para o outro sistema consultar e gravar dados no CleanFin, veja Acessos de API.
Abrir a tela
No menu da esquerda, clique em Integrações e depois em Webhooks de API.
- Novo — cadastra um webhook.
- Instruções de integração — como os avisos chegam, para passar ao programador.
| As instruções dizem que | Na prática |
|---|---|
| Os avisos saem via POST, de um IP fixo do CleanFin (mostrado na tela). | O sistema do outro lado pode conferir o IP para saber que o aviso é mesmo do CleanFin. |
| O aviso leva os dados em JSON. | É o formato que o programador vai ler. |
| Se a resposta não for 200 ou 201, o CleanFin tenta de novo 10 vezes, em intervalos espaçados, por até 6 horas. | Se o sistema do outro lado ficar fora do ar por pouco tempo, o aviso não se perde. |
O link Abrir sandbox leva ao ambiente de homologação, para testar sem mexer nos dados reais.
Cadastrar um webhook
- Clique em Novo
No alto da tela. O formulário abre numa janela.
- Escolha o evento
Em Evento, o aviso que você quer receber. Hoje é ★CleanPay - Fatura.
- Informe a URL
O endereço https do sistema que vai receber o aviso. Não é permitido apontar para endereços de rede interna.
- Deixe Ativo marcado e salve
Salve no ✓ verde. A partir daí, cada mudança nas faturas CleanPay é avisada.
Assinatura dos avisos
Cada aviso vai assinado com um segredo que o CleanFin cria para o webhook ao salvar. A assinatura permite ao sistema do outro lado conferir que o aviso veio mesmo do CleanFin. Ao duplicar um webhook, a cópia ganha um segredo novo.
Acompanhar os envios
Nos três pontinhos de cada webhook:
- Ver logs de envio — a lista de avisos enviados, com os Dados enviados, o Retorno do outro sistema, o Status, o número de Tentativas e a data do Último envio. É aqui que se descobre por que um aviso não chegou.
- Excluir — apaga o webhook. Os avisos param.
Dúvidas comuns
O outro sistema diz que não recebeu o aviso
Abra Ver logs de envio no webhook. Se o Status não for 200 ou 201, o Retorno mostra o que o outro sistema respondeu. Confira também se a URL está certa e se o webhook está Ativo.
Posso cadastrar mais de um endereço?
Pode. Cada webhook ativo recebe os avisos do seu evento.