Polling vs. Webhooks

Digamos que um cliente entra no seu site/aplicação e realiza uma compra. O seu serviço de compras irá receber uma requisição, que irá enviar para o serviço de pagamentos, que irá chamar um gateway de pagamento do Asaas, correto?

Depois disso você tem duas formas de receber informações do Asaas:

Fazer polling

Após ter criado uma cobrança, a sua aplicação faz várias requisições no Asaas para verificar o status do pagamento, até que o Asaas retorne que ela foi paga.

Porém esta prática tem pontos negativos. Fazer polling implica em usar recursos tanto do lado da sua aplicação como no lado do Asaas. Podendo inclusive fazer sua chave de API ser bloqueada por quota limit.

Exemplo de polling

Aplicação cria cobrança
↓
GET /v3/payments/{id}
↓
GET /v3/payments/{id}
↓
GET /v3/payments/{id}
↓
Pagamento confirmado

Quanto menor o intervalo entre consultas, maior será o consumo de recursos e o número de chamadas à API.

Webhooks

Basicamente é um “me avise de volta em determinada URL quando você tem atualizações nesta cobrança”. Quando o Asaas finalizar o processamento de um pagamento, você receberá em sua URL configurada o status do mesmo.

Dessa forma o paradigma mudou e o seu serviço de pagamento não precisa gastar recursos para verificar o status de uma cobrança.

Exemplo de fluxo utilizando Webhooks

Aplicação cria cobrança
↓
Pagamento é processado
↓
Evento ocorre
↓
Asaas envia POST para seu endpoint
↓
Aplicação recebe a notificação
↓
Retorna HTTP 200

Exemplo de endpoint

POST https://api.exemplo.com/webhooks/asaas

Exemplo de payload

{
  "id": "evt_05b708f961d739ea7eba7e4db318f621",
  "event": "PAYMENT_RECEIVED",
  "payment": {
    "id": "pay_080225913252"
  }
}

Parâmetros e comportamentos importantes

Ao utilizar Webhooks, é importante considerar:

Algumas dicas interessantes na hora de usar Webhooks:

• Você deve desenvolver uma API do seu lado responsável por receber as requisições do Webhook;
• É interessante que você crie regras no seu endpoint por razões de segurança. O Asaas possibilita que você defina um authToken para cada Webhook, por exemplo;
• Caso algum problema aconteça na comunicação com sua API, a fila é interrompida e você recebe um e-mail de aviso.

Erros comuns e boas práticas

Evento duplicado

Os Webhooks utilizam o modelo at least once, portanto um mesmo evento pode ser enviado mais de uma vez.

Implemente idempotência para evitar processamentos duplicados.

Endpoint lento

Se a aplicação demorar muito para responder, novas tentativas poderão ser realizadas.

O ideal é processar os eventos de forma assíncrona e retornar HTTP 200 rapidamente.

Falhas de comunicação

Após diversas falhas consecutivas, a fila poderá ser interrompida.

Recomenda-se monitorar os Logs de Webhooks e corrigir rapidamente qualquer indisponibilidade.

Segurança

Utilize o header:

asaas-access-token

e, se possível, restrinja as chamadas aos IPs oficiais do Asaas.

Impactos operacionais

Além da economia de recursos, os Webhooks são uma garantia de que sua aplicação receberá um evento sempre que algo mudar no gateway.

O polling pode funcionar para verificar se uma cobrança foi paga, porém não te avisará em caso de atraso no pagamento de um boleto ou quando o pagamento de um cartão de crédito efetivamente caiu na sua conta.

Além disso, o polling aumenta o consumo da API e pode provocar uso desnecessário de recursos da aplicação.

A utilização de Webhooks é a forma mais prática e segura de manter sua aplicação atualizada sobre tudo que acontece no gateway do Asaas.

Próximos passos

Após configurar os Webhooks, recomendamos consultar:

• Receba eventos do Asaas no seu endpoint de Webhook;
• Como implementar idempotência em Webhooks;
• Eventos de Webhooks;
• Tipos de envio;
• Logs de Webhooks;
• Penalização de filas;
• Fila pausada.