DiscordStatus
Guias / Guides

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

Crie um endpoint HTTP capaz de receber e processar as notificações enviadas pelo Asaas.

Quando um evento configurado ocorre, o Asaas envia uma requisição POST para a URL do Webhook com o identificador do evento e os dados do recurso relacionado.

Antes de começar

Tenha um Webhook configurado:

Realize os primeiros testes no Sandbox e replique a configuração em Produção após homologar o fluxo.

Entenda o objeto de evento

Cada notificação contém:

  • id: identificador único do evento;
  • event: tipo do evento ocorrido;
  • objeto relacionado ao recurso, como payment, transfer ou subscription.

Exemplo:

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

Utilize o id do evento para identificar reenvios e implementar idempotência.

O formato do objeto relacionado varia conforme o evento. Consulte Eventos de Webhooks para conhecer os eventos disponíveis.

1. Crie o endpoint

Disponibilize uma URL pública capaz de receber requisições HTTP POST com payload JSON.

Exemplos básicos de recebimento:

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');
});

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]);
});

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));
    }
}

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})

Os exemplos mostram apenas o recebimento e a identificação do evento. Em Produção, persista o evento e execute regras de negócio de forma assíncrona.

2. Persista o evento antes de responder

Os Webhooks seguem o modelo de entrega at least once. O mesmo evento pode ser enviado mais de uma vez.

O fluxo recomendado é:

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

Utilize id como chave única para evitar processar novamente um evento já recebido.

Consulte como implementar idempotência em Webhooks.

3. Responda HTTP 200

Após confirmar a persistência do evento, responda:

HTTP/1.1 200 OK

Não aguarde processamentos demorados para responder ao Asaas.

Caso a entrega não seja confirmada, o evento entra no fluxo de novas tentativas. Após 15 falhas consecutivas, a fila do Webhook pode ser interrompida.

Entenda o comportamento da fila pausada.

4. Valide a autenticação

Se o Webhook estiver configurado com authToken, o valor será enviado no header:

asaas-access-token

Valide o token antes de aceitar a notificação.

📘

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.

Se sua infraestrutura restringe requisições por origem, consulte os IPs oficiais do Asaas.

5. Teste o recebimento

Se a aplicação estiver executando localmente, exponha o endpoint por uma URL pública para realizar os testes.

Ferramentas como:

  • ngrok;
  • Cloudflare Tunnel;

podem ser utilizadas para disponibilizar temporariamente essa URL.

No Sandbox:

  1. configure o Webhook;
  2. selecione os eventos que deseja testar;
  3. execute a operação correspondente;
  4. confirme o recebimento do POST;
  5. valide a persistência e o processamento do evento.

As configurações de Sandbox e Produção são independentes.

6. Consulte os Logs de Webhooks

Para validar entregas ou investigar falhas, acesse:

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

Nos logs você pode verificar:

  • payload enviado;
  • data e horário da tentativa;
  • código HTTP retornado;
  • quantidade de tentativas;
  • erros de comunicação e timeouts.

Consulte os Logs de Webhooks.

Erros comuns

Evento duplicado

O mesmo id pode ser entregue mais de uma vez.

Implemente idempotência e não repita a regra de negócio quando o evento já tiver sido processado.

Timeout

Processamentos demorados antes da resposta podem provocar falhas de entrega.

Persista o evento, responda HTTP 200 e processe-o em segundo plano.

HTTP 500

Verifique os Logs de Webhooks para identificar a exceção retornada pela aplicação.

Token inválido

Confirme se o valor recebido em asaas-access-token corresponde ao authToken configurado no Webhook.

HTTP 403

Verifique Firewall, WAF ou outras regras de acesso que possam estar bloqueando as requisições do Asaas.

Em Sandbox podem existir IPs adicionais aos utilizados em Produção.

Próximos passos

Updated 3 days ago

Did this page help you?