Webhooks

Durante a implementação da API poderão existir momentos em que você precisará aguardar alguma ação do cliente antes de prosseguir com seu processo. Suponha que você necessite confirmar o pagamento de uma fatura antes de enviar uma encomenda. Uma prática desaconselhável seria, por exemplo, agendar uma consulta diária ao webservice de faturas da Vindi para verificar o status de pagamento de todas as suas faturas pendentes.

Além de desperdiçar recursos de processamento, você também sofreria com o atraso entre o momento real do pagamento e da consulta do webservice. Isso poderia ser resolvido diminuindo o intervalo entre as consultas, porém dependendo do número de faturas abertas, este método tornaria-se inviável em pouco tempo.

Para resolver esse problema, inverte-se a responsabilidade da notificação: A Vindi avisará você quando alguma ação ocorrer. Este aviso é realizado através de um HTTP POST que a Vindi faz em uma URL que você pode configurar na plataforma. Estes avisos são chamados de webhooks.

Formato e método de envio

Todas as requisições geradas a partir de webhooks são efetuadas com o método POST, com o conteúdo no corpo (body) da requisição no formato JSON, incluindo os seguintes headers:

Content-Type: application/json; charset=UTF-8
User-Agent: Vindi-Hookshot/1.0

Veja abaixo mais detalhes sobre o conteúdo enviado.

A plataforma espera que sua aplicação responda com o código HTTP 2XX (200, 201, etc) em no máximo 20 segundos. Códigos de redirecionamento (3XX) não serão seguidos e serão considerados como falha.

Caso seja necessário, consulte a lista de endereços IP de origem para webhooks.

Retentativas

A plataforma Vindi irá efetuar 15 retentativas de envio caso seu sistema esteja fora do ar ou responda com um código HTTP diferente de 2xx. As retentativas são enviadas em intervalos progressivos durante aproximadamente 48 horas. Depois desse período a requisição é descartada pela Vindi.

Esteja ciente de que as requisições podem chegar até seu servidor em uma ordem diferente do disparo. Dependendo do ação desejada, recomendamos você faça uma consulta à API no momento em que receber o webhook para saber se as informações recebidas são as mais recentes.

Também é uma boa prática armazenar localmente o conteúdo do webhook antes de processá-lo, já que não é possível reenviá-los uma vez que seu endpoint tenha respondido de forma positiva com HTTP 2XX.

Conteúdo da requisição

Como mencionado acima, o conteúdo da requisição estará contido em seu no corpo (body), no formato JSON:

{  
  "event":{  
    "type":"subscription_created",
    "created_at":"2014-10-02T22:35:57.477-03:00",
    "data":{  
      "subscription":{  
        {...}
      }
    }
  }
}

O conteúdo do atributo data irá depender do tipo de evento enviado e respeitará o mesmo formato da API REST.

Eventos

Os seguintes eventos poderão ser habilitados através do painel de administração:

Evento type data
Assinatura cancelada subscription_canceled subscription
Assinatura efetuada subscription_created subscription
Assinatura reativada subscription_reactivated subscription
Cobrança emitida charge_created charge
Cobrança estornada charge_refunded charge
Cobrança cancelada charge_canceled charge
Cobrança rejeitada charge_rejected charge
Fatura emitida bill_created bill
Fatura paga bill_paid bill
Fatura cancelada bill_canceled bill
Fatura visualizada bill_seen bill
Período criado period_created period
Pendência gerada issue_created issue
Perfil de pagamento criado payment_profile_created payment_profile
Mensagem visualizada message_seen message

Whitelist e segurança

Apesar da plataforma enviar os webhooks através 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/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_exempt
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.

Tem mais dúvidas? Envie uma solicitação

Comentários

Powered by Zendesk