Eventos para chaves de API

Com estes eventos, você pode ser notificado em tempo real se uma chave for criada, habilitada, desabilitada ou excluída, mesmo que a ação seja realizada diretamente pela interface web. Isso é especialmente útil para contas-pai que gerenciam subcontas e precisam garantir a integridade de suas integrações.

Como utilizar

Para receber estes eventos, é necessário possuir um webhook configurado em sua conta. Os eventos relacionados às chaves de API serão enviados para a URL cadastrada sempre que ocorrer uma alteração em uma chave.

Recomendamos:

• validar a origem das requisições utilizando um authToken;
• responder com HTTP 200 após persistir o evento recebido;
• implementar idempotência utilizando o campo id do evento;
• preparar a aplicação para receber novos atributos sem gerar exceções.

Os Webhooks do Asaas seguem a premissa at least once, portanto um mesmo evento poderá ser reenviado em situações excepcionais.

Eventos disponíveis

Os eventos que o Asaas notifica são:

• ACCESS_TOKEN_CREATED - Geração de nova chave de API.
• ACCESS_TOKEN_ENABLED - Uma chave de API desabilitada foi reativada.
• ACCESS_TOKEN_DISABLED - Uma chave de API foi desabilitada, seja manualmente ou pelo nosso ciclo de vida automático.
• ACCESS_TOKEN_DELETED - Uma chave de API foi permanentemente removida.
• ACCESS_TOKEN_EXPIRING_SOON - Uma chave de API irá expirar em breve devido à inatividade. Este evento não é disparado para chaves com data de expiração manual.
• ACCESS_TOKEN_EXPIRED - Uma chave de API foi permanentemente expirada por inatividade ou devido à configuração manual.

Exemplo de JSON a ser recebido [POST]

A notificação consiste em um POST contendo um JSON, conforme este exemplo:

{
  "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

Os campos mais importantes para o processamento do evento são:

• id: identificador único do evento. Pode ser utilizado para implementar idempotência.
• event: tipo do evento recebido.
• accessToken.id: identificador da chave.
• accessToken.enabled: indica se a chave está habilitada.
• accessToken.disableReason: motivo da desativação da chave.
• accessToken.expirationDate: data de expiração configurada manualmente.
• accessToken.projectedExpirationDateByLackOfUse: previsão de expiração por inatividade.

Valores possíveis do disableReason

Boas práticas

• Responda com HTTP 200 após persistir o evento.
• Utilize o identificador do evento (id) para evitar processamentos duplicados.
• Prepare sua aplicação para receber novos campos no payload.
• Monitore falhas de processamento e implemente logs.
• Utilize um authToken para validar a origem das requisições.

🚧

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.

Conteúdos relacionados

• Receba eventos do Asaas no seu endpoint de Webhook;
• Criar novo Webhook pela aplicação web;
• Criar novo Webhook pela API;
• Como implementar idempotência em Webhooks;
• Logs de Webhooks;
• Fila pausada;
• IPs oficiais do Asaas.