Eventos para chaves de API

Receba notificações para monitorar todas as ações e mudanças de estado que ocorrem em suas chaves de API, aumentando a segurança e a visibilidade operacional da sua conta

Use os eventos de chaves de API para acompanhar criações, habilitações, desabilitações, exclusões e expirações sem consultar periodicamente o estado das chaves.

As notificações também são enviadas quando a alteração ocorre pela interface web. Em operações com subcontas, utilize os dados do evento para identificar qual conta teve a chave alterada.

Eventos disponíveis

Evento	Quando ocorre	Tratamento na integração
`ACCESS_TOKEN_CREATED`	Uma nova chave de API é criada.	Registre a chave pelo `accessToken.id` e sincronize seu estado.
`ACCESS_TOKEN_ENABLED`	Uma chave desabilitada é reativada.	Atualize a chave como habilitada.
`ACCESS_TOKEN_DISABLED`	Uma chave é desabilitada manualmente ou pelo ciclo de vida automático.	Atualize a chave como desabilitada e consulte `accessToken.disableReason`.
`ACCESS_TOKEN_DELETED`	Uma chave é permanentemente removida.	Remova ou invalide a referência da chave no seu sistema.
`ACCESS_TOKEN_EXPIRING_SOON`	Uma chave está próxima da expiração por inatividade.	Notifique ou execute as ações necessárias antes da expiração.
`ACCESS_TOKEN_EXPIRED`	Uma chave expira permanentemente por inatividade ou pela data de expiração configurada.	Considere a chave inválida para novas autenticações.

ACCESS_TOKEN_EXPIRING_SOON é relacionado ao ciclo de vida por inatividade e não é enviado para chaves que possuem uma data de expiração configurada manualmente.

Para conhecer os prazos e regras de expiração por inatividade, consulte Chaves de API.

Payload do evento

A notificação é enviada via POST com o evento e os dados atuais da chave.

{
  "id": "evt_6561b631fa5580caadd00bbe3b858607&9193",
  "event": "ACCESS_TOKEN_CREATED",
  "dateCreated": "2024-10-16 11:11:04",
  "account": {
    "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
    "ownerId": null
  },
  "accessToken": {
    "id": "cf7662a4-a7dd-40ec-b8de-d28617729501",
    "name": "Chave de TESTE",
    "enabled": false,
    "dateCreated": "2026-05-19 12:25:15",
    "disableReason": "MANUAL",
    "expirationDate": null,
    "projectedExpirationDateByLackOfUse": null
  }
}

Campos importantes do payload

Campo	Descrição
`id`	Identificador único do evento. Utilize-o para idempotência.
`event`	Identifica a alteração ocorrida na chave.
`account.id`	Identificador da conta relacionada ao evento.
`accessToken.id`	Identificador da chave.
`accessToken.enabled`	Indica se a chave está habilitada.
`accessToken.disableReason`	Motivo da desabilitação, quando aplicável.
`accessToken.expirationDate`	Data de expiração configurada manualmente.
`accessToken.projectedExpirationDateByLackOfUse`	Previsão de expiração por inatividade.

Use event para identificar a alteração que originou a notificação e os dados de accessToken para atualizar o estado da chave no seu sistema.

Valores possíveis de `accessToken.disableReason`

Valor	Cenário
`MANUAL`	Desabilitação manual pela aplicação web ou pela API.
`LACK_OF_USE`	Desabilitação automática por inatividade.

Como tratar os eventos

Para receber esses eventos, configure um Webhook da conta com os eventos ACCESS_TOKEN_* necessários para sua integração.

Ao receber uma notificação:

identifique a conta pelo campo account.id;
identifique a alteração pelo campo event;
persista o id para impedir processamento duplicado;
utilize accessToken.id para localizar a chave no seu sistema;
atualize o estado da chave com os dados recebidos;
responda HTTP 200 após confirmar a persistência e processe regras adicionais de forma assíncrona.

Os Webhooks seguem o modelo at least once, portanto o mesmo evento pode ser enviado mais de uma vez. O mesmo evento mantém o mesmo id em reenvios.

Consulte como implementar idempotência em Webhooks.

Quando utilizar authToken no Webhook, valide o header asaas-access-token para autenticar as notificações recebidas.

🚧
Atenção

Com a entrada de novos produtos e funções dentro do Asaas, é possível que novos atributos sejam incluídos no Webhook. É muito importante que seu código esteja preparado para não gerar exceções caso o Asaas devolva novos atributos não tratados pela sua aplicação, pois isso poderá causar interrupção na fila de sincronização.

Enviaremos um e-mail e avisaremos em nosso Discord quando novos campos forem incluídos no Webhook. O disparo será feito para o e-mail de notificação definido nas configurações do webhook.

Próximos passos

Updated 17 days ago

Did this page help you?