Eventos para Checkout

Os Webhooks são a melhor e mais segura forma de manter os dados da sua aplicação sincronizados com os eventos do Checkout do Asaas.

Sempre que ocorrer uma alteração relevante no ciclo de vida do Checkout, um evento poderá ser enviado para a URL configurada.

Quando utilizar

Os Webhooks de Checkout são recomendados quando sua aplicação precisa:

• acompanhar a criação de checkouts;
• identificar pagamentos realizados;
• detectar checkouts expirados;
• identificar cancelamentos;
• sincronizar pedidos, assinaturas ou serviços automaticamente;
• evitar consultas frequentes através de polling.

Como configurar os Webhooks do Checkout

A configuração utiliza o mesmo endpoint padrão de criação de Webhooks do Asaas.

POST /v3/webhooks

É necessário enviar o token de acesso da conta:

access_token

Exemplo:

{
  "name": "teste",
  "url": "https://minha-url.com",
  "sendType": "SEQUENTIALLY",
  "email": "[email protected]",
  "enabled": true,
  "interrupted": false,
  "events": [
    "CHECKOUT_CREATED",
    "CHECKOUT_CANCELED",
    "CHECKOUT_EXPIRED",
    "CHECKOUT_PAID"
  ]
}

O endpoint utilizado é o mesmo da configuração padrão dos Webhooks.

A única diferença é a lista de eventos monitorados.

Os eventos disponíveis são:

• CHECKOUT_CREATED - Checkout criado.
• CHECKOUT_CANCELED - Checkout cancelado.
• CHECKOUT_EXPIRED - Checkout expirado.
• CHECKOUT_PAID - Checkout pago.

Parâmetros importantes

Comportamentos importantes

Entrega no modelo at least once

Os Webhooks utilizam o modelo at least once, portanto um mesmo evento poderá ser enviado mais de uma vez.

Recomendamos implementar idempotência utilizando o campo:

id

Reenvio em caso de falha

Caso a aplicação retorne respostas diferentes da família HTTP 2xx, novas tentativas de entrega poderão ser realizadas.

Após falhas consecutivas, a fila poderá ser interrompida.

Processamento assíncrono

O ideal é responder rapidamente ao Asaas e realizar o processamento em segundo plano.

Fluxo recomendado:

Receber evento
↓
Persistir evento
↓
Responder HTTP 200
↓
Processar internamente

Ordem dos eventos

Quando configurado:

sendType = SEQUENTIALLY

os eventos são enviados sequencialmente.

Exemplo de requisição recebida

Após a configuração, o Asaas enviará requisições POST para a URL cadastrada.

Exemplo:

{
  "id": "evt_37260be8159d4472b4458d3de13efc2d&15370",
  "event": "CHECKOUT_CREATED",
  "dateCreated": "2024-10-31 18:07:47",
  "account": {
    "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
    "ownerId": null
  },
  "checkout": {
    "id": "2bd251f0-09b2-44ff-8a0c-a5cb29e5bbda",
    "link": null,
    "status": "ACTIVE",
    "minutesToExpire": 10,
    "billingTypes": [
      "MUNDIPAGG_CIELO"
    ],
    "chargeTypes": [
      "RECURRENT"
    ],
    "callback": {
      "cancelUrl": "https://google.com",
      "successUrl": "https://google.com",
      "expiredUrl": "https://google.com"
    },
    "items": [
      {
        "name": "teste2",
        "description": "teste",
        "quantity": 2,
        "value": 100
      },
      {
        "name": "teste2",
        "description": "teste2",
        "quantity": 2,
        "value": 100
      }
    ],
    "subscription": {
      "cycle": "MONTHLY",
      "nextDueDate": "2024-10-31T03:00:00+0000",
      "endDate": "2025-10-29T03:00:00+0000"
    },
    "installment": null,
    "split": [
      {
        "walletId": "c1ad713f-77fc-45b0-b734-b2ff9970d6d8",
        "fixedValue": 2,
        "percentualValue": null,
        "totalFixedValue": null
      },
      {
        "walletId": "c1ad713f-77fc-45b0-b734-b2ff9970d6d8",
        "fixedValue": null,
        "percentualValue": 2,
        "totalFixedValue": null
      }
    ],
    "customer": "cus_000000018936",
    "customerData": null
  }
}

Campos importantes do payload

Segurança

Recomendamos:

• validar o header asaas-access-token;
• responder rapidamente com HTTP 200;
• processar eventos de forma assíncrona;
• implementar idempotência;
• monitorar os Logs de Webhooks;
• permitir novos atributos no payload sem gerar exceções.

Erros comuns

Evento duplicado

Os Webhooks utilizam entrega at least once, portanto um evento pode ser reenviado.

Utilize o campo id para evitar processamentos duplicados.

Timeout no endpoint

Processamentos demorados podem provocar novas tentativas de entrega.

Responda HTTP 200 rapidamente e processe em segundo plano.

HTTP 500

Falhas internas impedem a confirmação da entrega e podem interromper a fila.

Novos campos no payload

Novos atributos poderão ser adicionados futuramente.

A aplicação deve ignorar campos desconhecidos.

Impactos operacionais

Falhas na integração podem provocar:

• novas tentativas de envio;
• interrupção da fila de sincronização;
• eventos duplicados;
• inconsistências entre sistemas;
• perda permanente dos eventos após 14 dias.

🚧

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.