Como configurar o Token de Autenticação no Webhook 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:

👉 https://www.asaas.com

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.