Receba eventos do Asaas no seu endpoint de webhook

Configure uma URL de webhook para manter sua aplicação sempre atualizada com a integração da API

Suggest Edits

Por que usar Webhooks?

Se ao criar uma integração você buscar que os dados de pagamento e clientes estejam sempre sincronizados com a sua aplicação, os webhooks são a melhor solução. Eles são como uma "API reversa", onde o Asaas realizará uma chamada HTTP em REST na sua aplicação.

Para habilitar o recebimento eventos de webhooks você precisa configurar a URL que receberá os eventos, o que pode ser feito via interface, acessando a aplicação web, ou via API. É possível cadastrar até 10 URLs de webhooks diferentes, e em cada uma você define quais eventos quer receber.

O objeto de evento

Eventos são objetos enviados em formato JSON via webhooks do Asaas. Eles são responsáveis por avisar quando algum evento aconteceu em sua conta.

Através dele você terá acesso ao id, event indicando qual seu evento e o objeto da entidade da qual o evento pertence, no exemplo abaixo temos o objeto payment com os dados da cobrança em questão.

{
   "id": "evt_05b708f961d739ea7eba7e4db318f621&368604920",
   "event":"PAYMENT_RECEIVED",
   "payment":{
      "object":"payment",
      "id":"pay_080225913252",
      ...
   }
}

Os webhooks são a forma que você usa para inscrever-se em eventos e receber notificações na sua aplicação sempre que o evento acontece.

Tipos de eventos

Os eventos são divididos por categorias relacionadas a entidade ao qual eles pertencem. Confira a página Eventos de Webhooks para conferir cada um.

Comece por aqui

Para começar a receber eventos através de webhooks na sua aplicação, siga os passos abaixo:

  1. Acesse o ambiente de Sandbox;
  2. Crie um endpoint na sua aplicação para receber requests HTTP do tipo POST;
  3. Configure seu webhook usando nossa aplicação web ou via API;
  4. Teste seu webhook;
  5. Realize debug em problemas com eventos;
  6. Após testado e validado, replique a configurações no ambiente de Produção;
  7. Mantenha seu webhook seguro.

Crie um endpoint

Crie um endpoint HTTP (para testes em localhost) e HTTPS (para uso em produção) que espera receber um objeto de evento em um evento de POST. Este endpoint também deve retornar o mais rápido possível uma resposta 200, para evitar problemas na fila de sincronização de eventos.

Abaixo um exemplo básico usando Node.js:

const express = require('express');
const app = express();

app.post('/payments-webhook', express.json({type: 'application/json'}), (request, response) => {
  const body = request.body;

  switch (body.event) {
    case 'PAYMENT_CREATED':
      const payment = body.payment;
      createPayment(payment);
      break;
    case 'PAYMENT_RECEIVED':
      const payment = body.payment;
      receivePayment(payment)
      break;
    // ... trate outos eventos
    default:
      console.log(`Este evento não é aceito ${body.event}`);
  }

  // Retorne uma resposta para dizer que o webhook foi recebido
  response.json({received: true});
});

app.listen(8000, () => console.log('Running on port 8000'));

Configure seu webhook

Você pode realizar a configuração de um novo webhook via aplicação web ou via API.

Recomendamos, para testar seu webhook e sua integração, que você primeiro precisa crie uma conta em Sandbox. Confira nossa documentação sobre o Sandbox e siga os passos. Você também pode seguir os tutoriais de criação de webhook:

Teste seu webhook

Com o webhook em Sandbox configurado, você pode testar seu código que está em localhost usando algumas aplicações que expõe o seu código local na web.

Recomendamos usar uma aplicação de confiança como o ngrok ou o Cloudflare Tunnel. Com ambas aplicações você pode definir uma url que pode utilizar na configuração do seu webhook.

Debugar integração com webhooks

Você pode facilmente debugar seu webhook através da nossa página de logs de Webhooks. Acesse Menu do Usuário > Integrações > Logs de Webhooks.

Nesta página você poderá visualizar todas as requisições enviadas via webhook para sua aplicação, qual o status retornado pelo seu servidor e também qual o conteúdo enviado. Essa página é relevante também quando você tiver problemas com a fila de sincronização pausada , confira a documentação para mais detalhes.

Mantenha seu webhook seguro

É altamente recomendado que você mantenha sua integração e todos os seus webhooks seguros. Como recomendação, o Asaas sugere:

  • Confie somente nos IPs do Asaas para chamadas em webhooks: você pode realizar o bloqueio via firewall em todos os IPs que realização chamadas nas suas URLs de webhooks, exceto os IPs oficiais do Asaas.
  • Configura um accessToken: ao criar um novo webhook, você pode definir um código único para ele. Crie uma hash forte, de preferência um UUID v4, e confira sempre o header asaas-access-token para certificar que esta é uma chamada legítima.

Updated 14 days ago