Allow list e segurança
Apesar da plataforma enviar os webhooks por meio de endereços IP específicos, para garantir a autenticidade das chamadas você deve configurar o usuário e senha na URL ou incluir um parâmetro secreto que seja validado do seu lado.
Exemplo com usuário e senha (HTTP Basic):
https://usuario:[senha@www.empresa.com](mailto:senha@www.empresa.com)/webhook
Exemplo com parâmetro secreto:
https://www.empresa.com/webhook?secret=fo9graB5ids9
Apesar da plataforma suportar o envio para endereços HTTP, recomendamos fortemente que seu endpoint suporte HTTPS. Não é possível configurar portas diferentes de 80 (HTTP) ou 443 (HTTPS).
Caso opte por receber os webhooks da Vindi via HTTPS, você deverá usar um certificado emitido por uma autoridade certificadora reconhecida, ou seja, o certificado do seu servidor não deverá ser autoassinado.
TLS mútuo
Opcionalmente você poderá informar um certificado cliente para garantir a origem dos webhooks. A plataforma Vindi apresentará este certificado na requisição ao seu servidor, sendo responsabilidade do mesmo aceitar ou recusar a requisição. Este certificado pode ser autoassinado.
Esta técnica também é conhecida como 2-way TLS ou MTLS. É importante não confundir o certificado do seu servidor com o certificado cliente.
Cross Site Request Forgery (CSRF) em aplicações Rails, Django, etc.
Aplicações desenvolvidas com Ruby on Rails ou Django costumam embutir uma proteção automática contra CSRF.
Embora seja uma boa prática, você precisará desabilitar esta proteção no endpoint onde deseja receber as requisições da Vindi.
- Rails:
protect_from_forgery :except => :webhook
- Django:
@csrf_exemp
def webhook(request):
Para mais informações sobre este assunto
Consulte a documentação do Rails ou do Django.
Para outros frameworks, busque na documentação pela sigla CSRF.
Testes
Antes de apontar o webhook para seu ambiente de produção, recomendamos testá-lo com o RequestBin. Esta ferramenta gera uma URL temporária onde você pode inspecionar as requisições realizadas pela Vindi.
Para direcionar testes de webhooks para o ambiente de desenvolvimento em seu próprio computador, recomendamos as ferramentas ngrok ou UltraHook.