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 a operação completa da loja no jogo e gerenciamento de pagamento, é necessário implementar o processamento dos webhooks principais:

O esquema abaixo demonstra o processo de comprar e retornar itens usando webhooks combinados.

  sequenceDiagram
    participant User
    participant GameClient as Game Client
    participant Xsolla
    participant GameServer as Game Server
    %% Item Purchase
        Note over User, GameServer: Item purchase
        User ->> GameClient: Logs in
        GameClient ->> Xsolla: Sends user authentication request
        Xsolla -->> GameClient: Returns JWT / OAuth 2.0 token
        GameClient ->> Xsolla: Sends JWT, project ID, pagination parameters
        Xsolla -->> GameClient: Returns array of items
        GameClient -->> User: Displays storefront
        User ->> GameClient: Selects item and clicks Buy
        GameClient ->> Xsolla: Creates order request
        Xsolla -->> GameClient: Returns payment token
        GameClient ->> Xsolla: Opens payment UI URL with received token
        Xsolla ->> GameServer: Sends User validation webhook
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Displays payment UI
        User ->> Xsolla: Chooses payment method and clicks Pay
        Xsolla ->> GameServer: Sends Successful payment for order webhook
        GameServer ->> GameServer: Grants purchases to user
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Shows successful purchase screen
    %% Refund / Chargeback
        Note over User, GameServer: Refund / Chargeback
        User ->> Xsolla: Requests refund or chargeback
        Xsolla ->> GameServer: Sends Order cancellation webhook
        GameServer ->> GameServer: Removes items from user inventory
        GameServer -->> Xsolla: Returns success status code
        Xsolla -->> User: Refunds the payment

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 ativar o recebimento de webhooks:

1. No projeto na Conta de Distribuidor, acesse a seção Settings > Webhooks.
2. No campo Webhook server, especifique o URL do seu servidor, onde você deseja receber webhooks no formato https://example.com. Você também pode especificar o URL que encontrar em uma ferramenta para testar webhooks.

3. 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.
4. 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 opções necessários como ativadas. Na linha de cada permissão, você pode ver a lista de webhooks afetados pelas configurações.

1. No projeto dentro da Conta de Distribuidor, vá para a seção Settings > Webhooks.
2. Clique em Disable webhooks.

Teste de webhooks na Conta de Distribuidor

Uma seção para testar webhooks é exibida na Conta de Distribuidor abaixo das configurações avançadas depois que você ativar webhooks no seu projeto.

Você pode testar os seguintes webhooks:

1. Na seção de testes de webhooks, acesse a aba Payments and Store.
2. No menu suspenso, selecione o tipo de item. Se o tipo de item selecionado não estiver configurado no seu projeto, você verá um botão para configurar os itens.
3. Preencha os campos necessários:
   • Xsolla order ID — ID de pedido no lado da Xsolla. Ao testar, você pode usar qualquer valor numérico.
   • Xsolla invoice ID — ID de transação no lado da Xsolla. Ao testar, você pode usar qualquer valor numérico.
   • Items — itens dos quais você deseja receber informações no webhook. Selecione o SKU dos itens na lista suspensa e indique a quantidade. Você pode escolher múltiplos itens do mesmo tipo pressionando + e adicionando-o em uma nova fileira.
   • User ID — ao testar, você pode usar qualquer combinação de letras de dígitos.
   • Invoice ID — ID de transação no lado do seu jogo. Ao testar, você pode usar qualquer combinação de letras de dígitos. Não é um parâmetro necessário para um pagamento bem-sucedido, mas você pode passá-lo para vincular o ID de transação do seu lado ao ID de transação no lado da Xsolla.
   • Amount — quantia de pagamento. Ao testar, você pode usar qualquer valor numérico.
   • Currency — selecione uma moeda da lista suspensa.
4. Clique em Testar webhook.

Os webhooks Successful payment for order, Order cancellation e User validation com os dados especificados são enviados ao URL fornecido. Os resultados dos testes ede cada tipo de webhook são exibidos abaixo do botão Test webhook. Para cada webhook, você precisa configurar o processamento de 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.

A lógica de retorno para os webhooks Payment e Refund é descrita na respectiva página de webhook.

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 Pagamento bem-sucedido do pedido não são enviados.

Configurando informações de item em webhooks

Você pode configurar quais dados de itens são inclusos nos webhooks Pagamento do pedido bem-sucedido e Cancelamento do pedido pela matriz items.

Habilitação da inclusão de parâmetros adicionais

Habilite a inclusão de parâmetros adicionais que indicam:

• se o item é grátis (is_free)
• se o item é um bônus (is_bonus)
• se o item faz parte de um conjunto (is_bundle_content)

Para receber esses parâmetros, você deve trocar seus webhooks para a versão 2 usando a chamada de API Atualizar informações sobre as configurações do webhook. Na versão 1 (padrão), esses parâmetros não estão disponíveis.

Exemplo de uma matriz de items com parâmetros adicionais:

 1"items": [
 2      {
 3        "sku": "com.xsolla.item_new_1",
 4        "type": "bundle",
 5        "is_pre_order": false,
 6        "is_free": false,
 7        "is_bonus": false,
 8        "is_bundle_content": false,
 9        "quantity": 1,
10        "amount": "1000",
11        "promotions": []
12      },
13      {
14        "sku": "com.xsolla.gold_1",
15        "type": "virtual_currency",
16        "is_pre_order": false,
17        "is_free": false,
18        "is_bonus": false,
19        "is_bundle_content": true,
20        "quantity": 1500,
21        "amount": "[null]",
22        "promotions": []
23      }
24 ]

Desativação da inclusão de conteúdos de conjunto

Por padrão, webhooks incluem todos os tipos de itens do conjunto como uma lista de itens individuais. Você pode configurar o webhook para incluir apenas o conjunto em si, sem listar seus conteúdos.

Nesse caso, os itens inclusos no conjunto não são inclusos na matriz items. Na matriz exibida acima, o item com o SKU com.xsolla.gold_1, que é parte do conjunto, é excluído.

Exemplo de uma matriz de items quando o conteúdo do conjunto está desativado:

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ]

Para desativar a inclusão de conteúdos do conjunto, entre em contato com seu Gerente de Sucesso do Cliente ou envie um e-mail para csm@xsolla.com.