Escolher eventos de webhook

A Chargefy cria um evento quando algo relevante acontece com um recurso: um pagamento é confirmado, uma assinatura muda ou um cliente é atualizado. Você escolhe quais tipos cada endpoint de webhook deve receber. Escute o resultado de negócio que precisa refletir no seu sistema. Não dependa do caminho usado para chegar a ele: o mesmo payment.intent.succeeded confirma um pagamento criado por checkout, link de pagamento ou API.

​

Três regras para escolher eventos

​

Evento e entrega são objetos diferentes

Um evento pode ter zero, uma ou várias entregas:

• sem endpoint inscrito, o evento continua disponível pela API;
• com um endpoint inscrito, a Chargefy cria uma entrega;
• com vários endpoints inscritos, cada endpoint recebe uma entrega independente do mesmo evento.

​

Escolha os tipos necessários

Comece pelo menor conjunto que cobre as mudanças relevantes para sua integração. Você pode atualizar a inscrição do endpoint quando precisar. Use o catálogo de eventos para consultar todos os tipos aceitos e abrir o payload específico de cada evento.

​

Chargefy for Platforms

​

Entenda o nome do evento

O type usa o formato namespace.action, sempre separado por pontos. Fluxos com mais etapas podem usar segmentos adicionais, como checkout.session.async.payment.succeeded. Novos tipos podem entrar no catálogo sem alterar os tipos já publicados. Seu handler deve responder 2xx e ignorar com segurança qualquer tipo que ainda não conheça.

​

Processe sem depender da ordem

Cada evento carrega o recurso em data.object. Em atualizações, data.previous_attributes pode trazer apenas os campos alterados e seus valores anteriores. O snapshot pertence ao momento em que o evento foi criado, não necessariamente ao estado mais recente no momento da entrega. Para efeitos terminais:

1. deduplique pelo event.id;
2. use o ID de data.object para consultar o recurso atual;
3. não deixe um evento atrasado rebaixar um pagamento já succeeded ou uma Checkout Session já paga;
4. responda 2xx depois de persistir o evento, antes de executar trabalho demorado.

O formato completo desses campos pertence à referência do objeto event. Assinatura, tentativas e timeout pertencem ao contrato de entrega de webhooks.

​

Investigue no Dashboard

As telas de Webhooks mostram cada entrega separadamente. Use-as para verificar:

• o endpoint e o horário da tentativa;
• o status HTTP ou timeout;
• a resposta retornada pelo seu servidor;
• as tentativas automáticas;
• a possibilidade de reentrega manual.

O evento não muda quando você o reenvia. O que muda é a entrega para o endpoint selecionado.

​

Próximos passos