Webhooks iLink

1. Âmbito

Neste modelo de comunicação, o ilink toma a iniciativa de comunicar ao ERP no momento que um determinado evento ocorre, dispensando de consultas frequentes ao API.

O ilink disponibiliza 2 webhooks:

• Webhook de novo documento - enviado ao receptor cada vez que um novo documento lhe é encaminhado
• Webhook de mudança de estado de documento - enviado ao emissor cada vez que um documento previamente emitido altera o seu estado

Para qualquer dos webhooks acima funcionar é necessário:

• Implementar um endpoint Web, disponível publicamente aos servidores do ilink, ao qual o ilink irá comunicar via HTTP. Os dados enviados do ilink para este URL público estão de acordo com o webhook que pretendem implementar (ver abaixo)
• Comunicar à equipa do ilink que pretendem implementar o Webhook específico para o vosso cliente, e indicar-nos uma chave de acesso e o URL público do vosso endpoint.

Este método, apesar de implementação mais extensa, tem a vantagem de evitar polling constante aos nossos servidores, consumir menos recursos em ambos os sistemas, e permite aceder a toda a informação em tempo real. Só recomendamos optar pela consulta manual caso existam implicações de segurança na abordagem dos Webhooks (ver abaixo).

2. Informação importante / Implicações de Segurança

Esta opção assume que o URL/porta em questão está disponível publicamente, ou pelo menos acessível aos nossos ambientes de testes e produção! Para tal, poderá ser necessário abrir portas ou criar as seguintes excepções no firewall da máquina que executa o serviço web:

• https://ilink.acin.pt (62.28.56.162:443) - testes
• https://ilink.pt (194.38.136.153:443 193.43.40.153:443) - produção

Nota: caso falhe o processo de comunicação de um documento, o ilink irá tentar comunicar novamente até 10 vezes nos próximos 7 dias, com intervalos incrementalmente maiores por cada tentativa. Após 10 tentativas falhadas de comunicação, o ilink irá deixar de tentar comunicar esse documento ao ERP.

Um documento é considerado entregue com sucesso ao ERP quando a reposta do webhook retorna um HTTP status code 200 (independentemente do conteúdo da resposta)

Nota: Na implementação deste endpoint, o ERP tem a responsabilidade de validar a chave de acesso e posteriormente registar a informação recebida no seu sistema. Recomendamos vivamente ao vosso sistema validar a chave de acesso enviada nos headers da nossa resposta, caso contrário estão a aceitar dados provenientes de origem desconhecida.

3. Webhooks

3.1 Webhook de novo documento

O webhook de novo documento é uma alternativa à consulta frequente de documentos por parte da entidade receptora. Cada vez que chega um novo documento a esta entidade, o callback de novo documento será invocado.

O endpoint implementado deverá esperar os seguintes dados desta especificação.

3.2 Webhook de mudança de estado de documento

O webhook de mudança de estado de documento é uma alternativa à consulta frequente dos estados de cada documento emitido por parte da entidade emissora. Cada vez que o receptor do um documento emitido aceitar, recusar ou receber o mesmo, este callback será invocado.

O endpoint implementado deverá esperar os seguintes dados desta especificação.