Receber eventos no seu endpoint
Configure uma URL de webhook para manter sua aplicação sempre atualizada com a integração da API.
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
, 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_00bfdbb32c9cd908d56e247e4a7622cd&368697207",
"event":"INVOICE_NFE_CREATED",
"dateCreated": "2024-06-12 16:45:03",
"invoiceNfe":{
"object":"invoice",
"id":"",
...
}
}
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:
- Acesse o ambiente de Sandbox;
- Crie um endpoint na sua aplicação para receber requests HTTP do tipo POST;
- Configure seu webhook usando nossa aplicação web ou via API;
- Teste seu webhook;
- Realize debug em problemas com eventos;
- Após testado e validado, replique a configurações no ambiente de Produção;
- Mantenha seu webhook seguro.
Crie um endpoint
Crie um endpoint 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('/invoice-webhook', express.json({type: 'application/json'}), (request, response) => {
const body = request.body;
const invoice = body.invoiceNfe;
switch (body.event) {
case 'INVOICE_NFE_CREATED':
createInvoice(invoice);
break;
case 'INVOICE_NFE_AUTHORIZED':
authorizedInvoice(invoice)
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'));
<?php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
Route::post('/invoice-webhook', function (Request $request) {
$body = $request->all();
$invoice = $body['invoiceNfe'];
switch ($body['event']) {
case 'INVOICE_NFE_CREATED':
createInvoice($invoice);
break;
case 'INVOICE_NFE_AUTHORIZED':
authorizedInvoice($invoice);
break;
// ... trate outros eventos
default:
Log::info('Este evento não é aceito ' . $body['event']);
}
return response()->json(['received' => true]);
});
function createInvoice($invoice) {
// Implementação do createInvoice
}
function authorizedInvoice($invoice) {
// Implementação do authorizedInvoice
}
import org.springframework.web.bind.annotation.*;
import org.springframework.http.ResponseEntity;
import java.util.Map;
@RestController
@RequestMapping("/invoice-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> invoice = (Map<String, Object>) body.get("invoiceNfe");
switch (event) {
case "INVOICE_NFE_CREATED":
createInvoice(invoice);
break;
case "INVOICE_NFE_AUTHORIZED":
authorizedInvoice(invoice);
break;
// ... trate outros eventos
default:
System.out.println("Este evento não é aceito " + event);
}
return ResponseEntity.ok(Map.of("received", true));
}
private void createInvoice(Map<String, Object> invoice) {
// Implementação do createInvoice
}
private void authorizedInvoice(Map<String, Object> invoice) {
// Implementação do authorizedInvoice
}
}
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/invoice-webhook', methods=['POST'])
def payments_webhook():
body = request.json
invoice = body['invoiceNfe']
if body['event'] == 'INVOICE_NFE_CREATED':
create_invoice(invoice)
elif body['event'] == 'INVOICE_NFE_AUTHORIZED':
authorized_invoice(invoice)
else:
print(f"Este evento não é aceito {body['event']}")
return jsonify({'received': True})
def create_invoice(invoice):
# Implementação do create_invoice
pass
def authorized_invoice(invoice):
# Implementação do authorized_invoice
pass
if __name__ == '__main__':
app.run(port=8000, debug=True)
Configure seu webhook
Você pode realizar a configuração de um novo webhook via aplicação web ou via API.
Recomendamos que você teste seu webhook e sua integração primeiramente em uma conta Sandbox. Confira nossa documentação sobre o Sandbox e siga os passos. Em seguida, você 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õem 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 Base ERP sugere:
- Confie somente nos IPs do Asaas para chamadas em webhooks: você pode realizar o bloqueio via firewall em todos os IPs que realizam chamadas nas suas URLs de webhooks, exceto os IPs oficiais do Asaas.
- Configure 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 headerasaas-access-token
para se certificar que esta é uma chamada legítima.
Updated 7 days ago