Estratégias de Identificação em Webhook PIX

Bom dia, @alessandrodev! A estratégia adotada depende muito das suas regras de negócio, por exemplo, você pode ter um webhook exclusivo para tratar recebimentos e outro exclusivo para tratar envios, se você utilizar o Split ainda pode ter um exclusivo para ele.

Caso prefira organizar todos em um único ponto, você teria o payload padrão de recebimento (endToEndId, txid, chave, valor, horario e infoPagador).

Se for um recebimento com split você terá tudo isso acrescido do gnExtras contendo pagador e split.

Para devolução é preciso que o recebimento já tenha existido, você pode adotar uma conferência interna do txid ou verificar a existência da propriedade devolucoes.

Já o envio de Pix terá as propriedades tipo e status e não terá o txid (virá em gnExtras o identificador do envio -> idEnvio).

Mais informações sobre o recebimento de callbacks na documentação: https://dev.efipay.com.br/docs/api-pix/webhooks/#recebendo-callbacks

Se você vai também enviar Pix, o melhor para separar é usar uma chave Pix diferente. Agora, na devolução de um Pix recebido, ela só vai acontecer se você pedir para fazer uma devolução. Então você pode ter algo ligado ao txid que te avise que foi solicitada devolução, e aí sim olhar o campo de devolucoes.

Mas o ponto é que todos são enviados para a mesma rota webhook/pix consigo cadastrar uma rota especifica para cada um? algo tipo webhook/pix/devolucoes ou webhook/pix?type=devolucoes para justamente não receber todas as variancias em um mesmo endpoint?

Boa tarde, @alessandrodev! Tudo bem?
Não, neste caso, como o cadastro do webhook é por chave, toda a movimentação (envvio, recebimento e devolução) relacionada a esta chave, vai ser enviada para o webhook cadastrado.
O conteudo de cada tipo de notificação é diferente: https://dev.efipay.com.br/docs/api-pix/webhooks#requisi%C3%A7%C3%A3o

humm, mas posso ter uma chave específica para tratar cada caso, certo? uma para recebimento, outra para devoluções etc?

Não. Ao emitir uma cobrança, você precisa informar um chave, então a confirmação de pagamento desta cobrança vai ser enviada para o webhook vinculado a chave informada.
Como a devolução esta associada a uma cobrança, que por sua vez esta associada a uma chave, o webhook de devolução vai ser enviada para a mesma url.

Dá para separar a chave de recebimento (e suas devoluções) da de envio.

vou fazer algumas simulações e testar