O Token de Autenticação do Webhook no Asaas é um recurso de segurança utilizado para validar que as notificações enviadas realmente vieram do Asaas.
Quando configurado, o Asaas envia automaticamente um header chamado:
asaas-access-token
em todas as requisições do webhook.
Seu sistema deve validar esse token antes de processar os eventos recebidos.
O que é o Token de Autenticação do Webhook?
O token é uma chave personalizada definida pelo próprio cliente dentro da configuração do webhook.
Ele serve para:
- Garantir mais segurança na integração
- Validar a origem das notificações
- Evitar chamadas falsas no endpoint
- Proteger o sistema contra requisições indevidas
Como configurar o Token no Webhook do Asaas
1. Acesse sua conta Asaas
Entre no painel:
2. Vá até a área de Webhooks
No menu lateral:
- Clique em Integrações
- Depois em Webhooks
3. Crie ou edite um Webhook
Você pode:
Criar um novo webhook
ou
Editar um webhook já existente
Informe normalmente:
- URL do endpoint
- Eventos desejados
- Configurações da integração
4. Preencha o campo “Token de autenticação”
Na configuração do webhook haverá um campo chamado:
- Token de autenticação
- Digite um token personalizado.
Exemplo:
meu_token_super_seguro_123
⚠️ Utilize um token forte e difícil de adivinhar.
5. Salve o Webhook
Após salvar, o Asaas começará a enviar o seguinte header em todas as requisições:
asaas-access-token: meu_token_super_seguro_123
Como validar o token no seu sistema
Seu backend deve comparar o valor recebido no header com o token configurado.
Exemplo em PHP
$tokenRecebido = $_SERVER['HTTP_ASAAS_ACCESS_TOKEN'];
if ($tokenRecebido !== 'meu_token_super_seguro_123') {
http_response_code(401);
exit('Token inválido');
}
Exemplo em Node.js (Express)
app.post('/webhook', (req, res) => {
const token = req.headers['asaas-access-token'];
if (token !== 'meu_token_super_seguro_123') {
return res.status(401).send('Token inválido');
}
res.sendStatus(200);
});
Exemplo em Laravel
$token = $request->header('asaas-access-token');
if ($token !== env('ASAAS_WEBHOOK_TOKEN')) {
abort(401, 'Token inválido');
}
Boas práticas de segurança
✅ Utilize tokens longos e complexos
✅ Armazene o token em variável de ambiente
✅ Nunca exponha o token no frontend
✅ Valide o header antes de processar o webhook
✅ Retorne erro 401 quando o token for inválido
Problemas comuns
- Header não está chegando
Verifique:
- Se o token foi realmente configurado no webhook
- Se o webhook foi salvo após a configuração
- Se seu servidor recebe headers customizados
- Token inválido
Confira:
- Espaços extras
- Letras maiúsculas/minúsculas
- Se o token do sistema é igual ao configurado no Asaas
Conclusão
O Token de Autenticação do Webhook é uma camada adicional de segurança extremamente importante nas integrações com o Asaas.
Ao configurar e validar corretamente o header asaas-access-token, seu sistema garante que apenas notificações legítimas sejam processadas.
Comentários (0)
Deixe seu comentário