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

Se você quiser receber notificações de eventos, implemente o tratamento de webhook:

• 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 Payment foi processado com êxito e contém informações sobre itens comprados e o ID da transação.
• 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.

• User validation — é enviada em diferentes estágios do processo de pagamento para garantir que o usuário esteja cadastrado no jogo. Contém informações sobre o usuário que compra a chave do jogo.

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.

Se você estiver usando um ID externo (ID de transação em seu sistema) e quiser associá-lo a um ID de transação no lado da Xsolla ou passar parâmetros adicionais da transação, implemente o webhook Transaction’s ID linking.

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.

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:

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

• Loja
• Payments

Observação

Para testes, você deve criar pelo menos um pacote de chaves de jogo.

Na aba Store, você pode testar os seguintes webhooks:

• Pagamento do pedido bem-sucedido (order_paid)
• Cancelamento do pedido (order_canceled)

1. No bloco de teste de webhook, navegue até a aba Store.
2. No menu suspenso, selecione Game Keys. Se os pacotes de chaves de jogo não estiverem configurados na Conta de Distribuidor, um dos seguintes botões será exibido:
   • Connect – se o módulo Game Keys não estiver conectado
   • Configure – se você conectou o módulo anteriormente, mas não concluiu a configuração

3. Insira qualquer valor no campo Xsolla Order ID.
4. Selecione o pacote de chaves de jogo na lista suspensa.
5. Especifique as plataformas de distribuição de jogos.
6. Especifique um valor arbitrário da chave de jogo no campo Amount.
7. Escolha a moeda em que o pedido será pago.
8. Clique em Test.

Webhooks Successful payment of the order e Order cancellation com os dados especificados são enviados para o URL fornecido. Os resultados do teste de cada tipo de webhook são exibidos abaixo dos botões Test.

Observação

Se aparecer uma mensagem de erro no bloco de teste informando que o teste não foi aprovado, verifique as configurações de resposta do webhook no webhook listener. Informações sobre esses erros estão disponíveis nos resultados do teste.

Na aba Payments, você pode testar os seguintes webhooks:

• Validação do usuário (user_validation)
• Pagamento (payment)

Para testar:

1. Na seção de testes, vá para a aba Payments.
2. Preencha os campos necessários:
   • User ID — Ao testar, você pode usar qualquer combinação de letras e dígitos.
   • Public user ID — ID conhecido a um usuário, como um e-mail ou apelido. Esse campo é exibido se o ID de usuário público estiver habilitado no seu projeto na seção Pay Station > Settings > Additional settings.
   • Currency — Selecione uma moeda na lista suspensa.
   • Xsolla Invoice ID — ID de transação no lado Xsolla. Ao testar, você pode usar qualquer valor numérico.
   • Amount — Quantia do pagamento. Ao testar, você pode usar qualquer valor numérico.
   • Invoice ID — ID de transação no lado do jogo. Ao testar, você pode usar qualquer combinação de letras e dígitos. Não é um parâmetro obrigatório para um pagamento bem-sucedido, mas você pode passá-lo para vincular o ID da transação no seu lado ao ID da transação no lado Xsolla.
3. Clique em Test webhooks.

No URL especificado, você receberá webhooks com dados preenchidos. Os resultados dos testes de cada webhook, tanto no cenário bem-sucedido quanto no cenário com um erro, são exibidos sob o botão Test webhooks. Se o ID de usuário público estiver habilitado no seu projeto, você também verá os resultados de uma verificação de pesquisa de usuário.

Para cada webhook, você precisa configurar o processamento para ambos cenários: um bem-sucedido e um com um erro.

Ao salvar o URL no campo Webhook server, você pode ver a seção Advanced settings onde você pode conceder permissões para receber informações detalhadas nos webhooks. Para fazer isso, defina as respectivas opções como On. Na linha de cada permissão, você pode ver a lista de webhooks afetados pelas configurações.

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.