Configurar webhooks

Webhooks são notificações sobre eventos que ocorrem no sistema. Quando um evento específico ocorre, a Xsolla envia uma solicitação HTTP, na qual os dados do evento são transmitidos ao seu aplicativo. Isso normalmente é uma solicitação POST no formato JSON.

Exemplos de evento:

  • interação de usuário com um catálogo de itens
  • pagamento ou cancelamento de um pedido

Lista de webhooks

Para operar plenamente uma loja no jogo, é necessário implementar o processamento dos principais webhooks:

  • Pagamento — é enviado quando um pedido é pago e contém dados de pagamento e detalhes da transação.
  • Successful payment of the order — é enviado quando um webhook Pagamento é processado com êxito e contém informações sobre itens comprados e o ID da transação. Use os dados do webhook para adicionar itens ao usuário.
  • Refund — é enviado quando um pedido é cancelado e contém os dados de pagamento cancelados e detalhes da transação.
  • Order cancellation — é enviado quando um webhook Refund foi processado com êxito e contém informações sobre os itens comprados e o ID da transação cancelada. Use os dados do webhook para remover os itens comprados.
  • User validation — é enviado em diferentes estágios do processo de pagamento para garantir que o usuário esteja cadastrado no jogo.

Abaixo, temos um esquema de compra e devolução de produtos no site usando webhooks desta lista.

Se a personalização do catálogo de itens for implementada no lado do aplicativo, configure o processamento da personalização do catálogo no lado do parceiro.

Observação
Para receber pagamentos reais, você só precisa implementar o processamento dos webhooks Pagamento, Successful payment of the order e User validation, bem como assinar o contrato de licenciamento.
Observação
Você pode usar a integração do PlayFab para receber informações de pagamento e cancelamento de pedidos em vez de usar webhooks.

Configuração de webhooks na Conta de Distribuidor

Para habilitar o recebimento de webhooks:

  1. Abra seu projeto na Conta de Distribuidor.
  2. Clique em Project settings no menu lateral e vá para a aba Webhooks.
  3. No campo Webhook server, especifique o URL do seu servidor onde deseja receber os webhooks no formato https://example.com. Você também pode especificar o URL que você encontra em uma ferramenta para testar webhooks.
  4. É gerada uma chave secreta para assinar webhooks de projeto por padrão. Se desejar gerar uma nova chave secreta, clique no ícone de atualização.
  5. Clique em Enable webhooks.

Observação
Para testar webhooks, você pode selecionar qualquer site dedicado, tal como webhook.site, ou uma plataforma, tal como ngrok.
Aviso
Não é possível enviar webhooks a URLs diferentes. O que você pode fazer na Conta de Distribuidor é especificar um URL de teste primeiro e então substituí-lo pelo real.
Para desativar o recebimento de webhooks:
  1. Abra seu projeto na Conta de Distribuidor.
  2. Clique em Project settings no menu lateral e vá para a aba Webhooks.
  3. Clique em Disable webhooks.

Teste de webhooks na Conta de Distribuidor

Você pode testar o recebimento dos seguintes webhooks:

Nome do webhookTipo de webhook
Validação do usuáriouser_validation
Pagamentopayment
Cancelamento de pedidoorder_canceled
Successful payment of the orderorder_paid

Se os webhooks forem configurados com êxito, um bloco de teste de webhook será exibido abaixo do bloco de configuração do webhook.

Ouvinte de webhooks

O ouvinte de webhooks é um código de programa que permite receber webhooks de entrada em um endereço URL especificado, ao gerar uma assinatura e ao enviar uma resposta para o servidor webhook da Xsolla.

Geração de assinatura

Ao receber um webhook, você deve garantir a segurança da transmissão de dados. Para fazer isso, você deve gerar uma assinatura a partir dos dados do webhook e verificar se ela corresponde à assinatura enviada no cabeçalho da solicitação HTTP.

Para gerar uma assinatura:

  1. Concatene o JSON do corpo da solicitação e da chave secreta do projeto.
  2. Aplique a função de hash criptográfico SHA-1 à cadeia de caracteres obtida na primeira etapa.

Enviando respostas ao webhook

Para confirmar o recebimento do webhook, seu servidor deve retornar:

  • O código HTTP 200, 201 ou 204 no caso de uma resposta bem-sucedida.
  • O código HTTP 400 com uma descrição do problema se o usuário especificado não for encontrado ou uma assinatura inválida for passada.

Seu manipulador de webhook também pode retornar um código 5xx em caso de problemas temporários em seu servidor.

Se uma resposta não foi recebida para os webhooks Successful payment of the order e Order cancellation, ou se uma resposta com um código 5xx for recebida, os webhooks são reenviados de acordo com o seguinte cronograma:

  • 2 tentativas com um intervalo de 5 minutos
  • 7 tentativas com um intervalo de 15 minutos
  • 10 tentativas com intervalo de 60 minutos

No máximo 20 tentativas de envio de webhooks são feitas dentro de 12 horas a partir da primeira tentativa.

Se uma resposta não for recebida pelo webhook Pagamento ou se uma resposta com um código 5xx for recebida, os webhooks também são reenviados com um intervalo de tempo maior. São feitas 12 tentativas no máximo dentro de 12 horas.

Se uma resposta não for recebida pelo webhook Validação do usuário ou for recebida uma resposta com um código 400 ou 5xx, o webhook Validação do usuário não é reenviado.

Nesse caso, um erro é exibido ao usuário e os webhooks Pagamento e Successful payment of the order não são enviados.

Observação
A lista completa e o mecanismo dos webhooks, juntamente com exemplos detalhados de seu processamento, estão descritos na documentação de webhooks.
Este artigo foi útil?
Obrigado!
Podemos melhorar alguma coisa? Mensagem
Que pena ouvir isso
Explique porque este artigo não foi útil para você. Mensagem
Obrigado pelo seu feedback!
Avaliaremos sua mensagem e a usaremos para melhorar sua experiência.
Última atualização: 11 de Setembro de 2024

Encontrou um erro de texto ou digitação? Selecione o texto e pressione Ctrl+Enter.

Relatar um problema
Nós sempre avaliamos nossos conteúdos. Seu feedback nos ajuda a melhorá-los.
Forneça um e-mail para que possamos responder
Obrigado pelo seu feedback!