Eventos de Webhooks

Os eventos permitem que sua aplicação reaja automaticamente às alterações dos recursos do Asaas.

Use esta página para localizar os eventos disponíveis para cada produto. Os nomes, payloads e comportamentos específicos ficam nas páginas de cada categoria.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Evento ocorre no Asaas"] --> B["Gerar o evento"]
    B --> C["Enviar o Webhook"]
    C --> D["Persistir o evento"]
    D --> E["Responder HTTP 200"]
    E --> F["Processar a atualização"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px

    class A inicio
    class B,C,D,E validacao
    class F sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Os Webhooks seguem o modelo at least once. Um mesmo evento pode ser enviado mais de uma vez, portanto utilize o id para implementar idempotência.

Estrutura de um evento

Os eventos seguem uma estrutura semelhante:

{
  "id": "evt_05b708f961d739ea7eba7e4db318f621",
  "event": "PAYMENT_RECEIVED",
  "dateCreated": "2024-06-12 16:45:03",
  "payment": {
    "id": "pay_080225913252"
  }
}

Os campos principais são:

O objeto retornado varia conforme a categoria e o evento recebido.

Escolha os eventos da sua integração

Configure somente os eventos necessários para a lógica da sua aplicação.

A página específica de cada recurso informa quais eventos podem ser recebidos e como interpretar o respectivo payload.

Ao receber um evento

Sua aplicação deve:

1. identificar o evento pelo campo event;
2. persistir o id para evitar processamento duplicado;
3. responder HTTP 200 após confirmar a persistência;
4. processar a regra de negócio de forma assíncrona.

Para implementar esse fluxo, consulte:

• Receba eventos do Asaas no seu endpoint de Webhook
• Como implementar idempotência em Webhooks

Eventos em subcontas

Próximos passos

• Receba eventos do Asaas no seu endpoint de Webhook
• Implemente idempotência em Webhooks
• Escolha o tipo de envio
• Monitore os Logs de Webhooks