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 vender chaves de jogo, a validação do usuário e a creditação dos itens não são necessários. Você pode conectar webhooks se quiser receber informações sobre eventos, tais como de pagamento ou de cancelamento de pedido.

Se você conectar webhooks, é importante processar todos os webhooks necessários por vir.

Para trocar à nova opção de recebimento de webhooks combinados, contate seus Gerentes de Sucesso do Cliente ou envie um e-mail para csm@xsolla.com.

Para a operação completa da loja no jogo e gerenciamento de pagamento, é necessário implementar o processamento dos webhooks principais:

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.

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. Uma chave secreta para assinar webhooks de projeto é gerada por padrão. Se quiser gerar uma nova chave secreta, clique no ícone de atualização.
5. Clique em Ativar webhooks.

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.

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

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

A seção de testes na Conta de Distribuidor varia dependendo da opção de recebimento de webhook.

O processo de teste para o cenário com webhooks combinados é descrito abaixo. Na aba Payments and store, você pode testar os seguintes webhooks:

• Validação de usuário (user_validation)
• Pagamento do pedido bem-sucedido (order_paid)
• Cancelamento do pedido (order_canceled)

Para testar:

1. Na seção de testes de webhooks, acesse a aba Payments and 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. Preencha os campos necessários:
   1. Insira qualquer valor no campo Xsolla Order ID.
   2. Selecione o pacote de chaves de jogo da lista suspensa.
   3. Especifique as plataformas de distribuição do jogo.
   4. User ID — Ao testar, você pode usar qualquer combinação de letras e dígitos.
   5. 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.
   6. Xsolla Invoice ID — ID de transação no lado Xsolla. Ao testar, você pode usar qualquer valor numérico.
   7. 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.
   8. Quantia — quantia de pagamento. Ao testar, você pode usar qualquer valor numérico.
   9. Moeda — selecione uma moeda da lista suspensa.
4. Clique em Testar webhook.

Webhooks Validação de usuário, Pagamento bem-sucedido do pedido e Cancelamento de pedido 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. Se o ID de usuário público está ativado em seu projeto, você também verá o resultado 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.

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 o servidor da Xsolla não receber uma resposta aos webhooks Pagamento bem-sucedido do pedido e Cancelamento de pedido, ou receber uma resposta com um código 5xx, 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 o servidor da Xsolla não receber uma resposta ao webhook Pagamento ou Reembolso, ou se receber uma resposta com um código 5xx, 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 o servidor da Xsolla não receber uma resposta ao webhook Validação do usuário ou receber 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.

Última atualização: 23 de Janeiro de 2025