Receba eventos do Asaas no seu endpoint de Webhook

Siga este tutorial para criar seu primeiro Webhook.

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, ao atributo event, que indica qual evento ocorreu, e ao objeto da entidade relacionada. No exemplo abaixo, temos o objeto payment contendo os dados da cobrança.

{
   "id": "evt_05b708f961d739ea7eba7e4db318f621&368604920",
   "event":"PAYMENT_RECEIVED",
   "dateCreated": "2024-06-12 16:45:03",
   "payment":{
      "object":"payment",
      "id":"pay_080225913252"
   }
}

Os Webhooks são a forma utilizada para receber notificações automaticamente sempre que um evento ocorrer na sua conta.

Tipos de eventos

Os eventos são divididos por categorias relacionadas às entidades do Asaas.

Consulte a página Eventos de Webhooks para visualizar todos os eventos disponíveis.

Comece por aqui

Para começar a receber eventos através de Webhooks:

Acesse o ambiente de Sandbox;
Crie um endpoint capaz de receber requisições HTTP POST;
Configure o Webhook pela aplicação web ou via API;
Teste sua integração;
Realize o debug em caso de falhas;
Após validar tudo em Sandbox, replique a configuração em Produção;
Implemente medidas de segurança.

Crie um endpoint

Crie um endpoint que receba requisições HTTP POST contendo um objeto de evento.

Recomenda-se responder o mais rapidamente possível com HTTP 200 para evitar problemas na fila de sincronização.

Exemplo em Node.js

const express = require('express');

const app = express();

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

    const body = request.body;
    const payment = body.payment;

    switch (body.event) {

      case 'PAYMENT_CREATED':
        createPayment(payment);
        break;

      case 'PAYMENT_RECEIVED':
        receivePayment(payment);
        break;

      default:
        console.log(`Evento não tratado: ${body.event}`);
    }

    return response.json({
      received: true
    });
  }
);

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

Exemplo em PHP

<?php

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;

Route::post('/payments-webhook', function (Request $request) {
    $body = $request->all();

    switch ($body['event']) {
        case 'PAYMENT_CREATED':
            createPayment($body['payment']);
            break;

        case 'PAYMENT_RECEIVED':
            receivePayment($body['payment']);
            break;

        default:
            Log::info('Evento não tratado: ' . $body['event']);
    }

    return response()->json(['received' => true]);
});

Exemplo em Java

@RestController
@RequestMapping("/payments-webhook")
public class WebhookController {

    @PostMapping(consumes = "application/json")
    public ResponseEntity<Map<String, Boolean>> handleWebhook(@RequestBody Map<String, Object> body) {

        String event = (String) body.get("event");
        Map<String, Object> payment = (Map<String, Object>) body.get("payment");

        switch (event) {

            case "PAYMENT_CREATED":
                createPayment(payment);
                break;

            case "PAYMENT_RECEIVED":
                receivePayment(payment);
                break;

            default:
                System.out.println("Evento não tratado " + event);
        }

        return ResponseEntity.ok(Map.of("received", true));
    }
}

Exemplo em Python

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/payments-webhook', methods=['POST'])
def payments_webhook():

    body = request.json

    if body['event'] == 'PAYMENT_CREATED':
        create_payment(body['payment'])

    elif body['event'] == 'PAYMENT_RECEIVED':
        receive_payment(body['payment'])

    return jsonify({'received': True})

Comportamentos importantes

Entrega no modelo "at least once":

Os Webhooks do Asaas utilizam o modelo de entrega at least once.

Isso significa que um mesmo evento pode ser enviado mais de uma vez.

Por esse motivo, recomenda-se implementar idempotência.

Reenvio em caso de falha:

Caso a aplicação não responda com um código HTTP da família 2xx, novas tentativas de entrega serão realizadas.

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

Processamento assíncrono:

Recomenda-se responder rapidamente ao Asaas e processar os eventos internamente.

Fluxo recomendado:

Receber evento
↓
Persistir em fila
↓
Responder HTTP 200
↓
Processar regras de negócio

Ordem dos eventos:

Quando uma fila interrompida é reativada, os eventos pendentes são reenviados em ordem cronológica.

Configure seu Webhook

Você pode configurar Webhooks:

pela aplicação web;
via API.

Recomenda-se realizar os primeiros testes em Sandbox.

Guias:

Teste seu Webhook

Caso sua aplicação esteja rodando localmente, é possível expô-la utilizando ferramentas como:

ngrok;
Cloudflare Tunnel.

Essas ferramentas geram uma URL pública que poderá ser configurada no Webhook.

Debugar integração com Webhooks

Você pode acompanhar os envios através da página de Logs de Webhooks.

Acesse:

Menu do Usuário > Integrações > Logs de Webhooks

Nesta página é possível visualizar:

payload enviado;
horário da tentativa;
código HTTP retornado pelo servidor;
quantidade de tentativas;
erros de comunicação.

Esses logs são especialmente úteis quando há problemas de sincronização ou fila pausada.

Erros comuns

Timeout no endpoint:

Processamentos demorados podem gerar novas tentativas de entrega.

Recomenda-se responder rapidamente e processar os dados em segundo plano.

HTTP 500:

Falhas internas da aplicação impedem a confirmação da entrega.

Consulte os Logs de Webhooks para identificar a causa.

Evento duplicado:

Como a entrega segue o modelo "at least once", um mesmo evento pode chegar mais de uma vez.

Implemente idempotência utilizando o identificador do evento.

Token inválido:

Caso utilize um token de autenticação, sempre valide o header:

asaas-access-token

Mantenha seu Webhook seguro

É altamente recomendado proteger seus endpoints.

Permita apenas os IPs do Asaas:

Configure o firewall para aceitar chamadas somente dos IPs oficiais do Asaas.

Utilize um authToken:

Configure um token e valide sempre o header:

asaas-access-token

📘
Definindo um token seguro
O token deve:

possuir entre 32 e 255 caracteres;

não conter espaços em branco;

não utilizar sequências simples;

não ser uma API Key do Asaas.

Impactos operacionais

Falhas no endpoint podem provocar:

novas tentativas de entrega;
aumento do volume de requisições;
interrupção da fila após falhas consecutivas;
perda permanente dos eventos após 14 dias;
inconsistências entre sistemas caso não exista idempotência.

Por esse motivo, recomenda-se:

monitorar continuamente os Logs de Webhooks;
responder rapidamente ao Asaas;
processar eventos de forma assíncrona;
implementar idempotência;
testar inicialmente em Sandbox.

Próximos passos

Após receber os primeiros eventos, recomendamos consultar: