Polling vs. Webhooks

Polling e Webhooks permitem acompanhar alterações nos recursos da API, mas atendem a necessidades diferentes.

Para acompanhar mudanças de estado continuamente, prefira Webhooks. Utilize consultas GET quando precisar recuperar o estado atual de um recurso sob demanda.

Qual abordagem utilizar?

Polling

No polling, sua aplicação consulta repetidamente a API até identificar uma mudança no recurso.

Em uma cobrança, por exemplo, a aplicação pode consultar o pagamento até encontrar o estado esperado.

Fluxo com polling

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Criar a cobrança"] --> B["Consultar a cobrança"]
    B --> C{"Pagamento confirmado?"}

    C --> CSim(("Sim"))
    C --> CNao(("Não"))

    CSim --> D["Atualizar a aplicação"]
    CNao --> E["Aguardar novo intervalo"]
    E --> B

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,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

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px

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

    class CSim respostaSim
    class CNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 2 stroke:#22C55E,stroke-width:4px
    linkStyle 3 stroke:#EF4444,stroke-width:4px

Quanto menor o intervalo entre consultas, maior o número de requisições realizadas.

O uso frequente de polling também consome os limites da API e pode resultar em HTTP 429 Too Many Requests quando esses limites são atingidos.

Consulte os Limites da API.

Webhooks

Com Webhooks, sua aplicação não precisa consultar repetidamente a API para descobrir se um evento ocorreu.

Quando houver um evento configurado, o Asaas envia uma requisição POST para o endpoint da sua aplicação.

Fluxo com Webhooks

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Criar a cobrança"] --> B["Aguardar o evento"]
    B --> C["Receber o Webhook"]
    C --> D["Persistir o evento"]
    D --> E["Responder HTTP 200"]
    E --> F["Atualizar a aplicaçã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

Exemplo de endpoint

POST https://api.exemplo.com/webhooks/asaas

Exemplo de payload

{
  "id": "evt_05b708f961d739ea7eba7e4db318f621",
  "event": "PAYMENT_RECEIVED",
  "payment": {
    "id": "pay_080225913252"
  }
}

O que considerar ao utilizar Webhooks

Como a entrega segue o modelo at least once, utilize o id do evento para implementar idempotência.

Consulte como implementar idempotência em Webhooks.

Próximos passos

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