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

Exemplos de eventos:

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

Quando um evento definido acontece, a Xsolla notifica o seu sistema sobre o pagamento através de um webhook. Como resultado, você pode executar ações como:

• repor o saldo do usuário
• fazer um reembolso de pagamento
• creditar ou debitar novos itens da conta do usuário
• começar a fornecer uma assinatura
• bloquear um usuário em caso de suspeita de fraude

Exemplo de um fluxo de trabalho de webhook de processamento de pagamentos:

Guia de vídeo para integração de webhooks da Xsolla:

[espaço reservado para iframe]

Configurações de webhooks ao trabalhar com produtos e soluções Xsolla:

Produto/Solução	Obrigatório/Opcional	Para que servem os webhooks
Pagamentos	Obrigatório	Validação do usuário. Receber informações sobre dados da transação em casos de pagamento bem-sucedido ou reembolso de pagamento. Creditar itens comprados a um usuário e debitar itens em caso de cancelamento do pedido.
In-Game Store	Obrigatório	Validação do usuário. Receber informações sobre dados da transação em casos de pagamento bem-sucedido ou reembolso de pagamento. Creditar itens comprados a um usuário e debitar itens em caso de cancelamento do pedido.
Game Sales	Opcional	Para vender chaves de jogo, a validação do usuário e o ato de creditar itens não são necessários. Você pode conectar webhooks se quiser receber informações sobre eventos, como pagamento ou cancelamento de pedido. Se você conectar webhooks, é importante processar todos os webhooks necessários acionados.
Subscriptions	Opcional	Recebendo informações sobre criação, atualização ou cancelamento de uma assinatura. Como alternativa, você pode solicitar informações por meio da API.
Web Shop	Obrigatório	Validação do usuário. Receber informações sobre dados da transação em casos de pagamento bem-sucedido ou reembolso de pagamento. Creditar itens comprados a um usuário e debitar itens em caso de cancelamento do pedido. Autenticação de usuários, se você usa autenticação via ID de usuário. Como alternativa, você pode usar autenticação de usuários via Xsolla Login.
Digital Distribution Hub	Obrigatório	Validação do usuário. Vinculando o ID de transação no lado da Xsolla com o ID da transação em seu sistema. Transferência de parâmetros de transação adicionais no pedido. Creditar itens comprados ao usuário e debitar itens em caso de cancelamento do pedido. Consulte a documentação para obter informações detalhadas sobre como configurar webhooks para o Digital Distribution Hub.

Se você usa produtos e soluções que exijam trabalhar com webhooks, habilite e teste os webhooks em sua Conta de Distribuidor e configure o processamento deles. Quando ocorrem eventos específicos, os webhooks são enviados sequencialmente. Portanto, se você não processar um dos webhooks, os webhooks subsequentes não serão enviados. A lista de webhooks necessários é apresentada abaixo.

2 opções de envio de webhook foram configuradas no lado da Xsolla ao comprar e devolver itens no site — informações com dados de pagamento e transação, e informações sobre itens comprados, podem vir separadamente ou podem ser combinadas em um webhook.

Recebimento de informações em webhooks combinados:

Se você se registrou na Conta de Distribuidor após 22 de janeiro de 2025, você receberá todas as informações nos webhooks Pagamento bem-sucedido do pedido (order_paid) e Cancelamento do pedido (order_canceled). Nesse caso, você não precisa processar os webhooks Pagamento (payment) e Reembolso (refund).

Recebimento de informações em webhooks separados:

Se você se registrou na Conta de Distribuidor até 22 de janeiro de 2025, você receberá os seguintes webhooks:

• Pagamento (payment) e Reembolso (refund) com informações sobre dados de pagamento e detalhes da transação.
• Pagamento bem- sucedido do pedido (order_paid) e Cancelamento do pedido (order_canceled) com informações sobre os itens comprados.

Você precisa processar todos os webhooks de entrada. Para alternar para a nova opção com o recebimento de webhooks combinados, entre em contato com seus Gerentes de Sucesso do Cliente ou envie um e-mail para csm@xsolla.com.

Para o pleno funcionamento gerenciamento da loja do jogo e de pagamentos, é necessário implementar o processamento dos principais webhooks.

Se você receber webhooks combinados:

Nome e tipo do webhook	Descrição
Validação de usuário > Validação de usuário (user_validation)	É enviado em diferentes estágios do processo de pagamento para garantir que o usuário esteja registrado no jogo.
Serviços de jogo > Webhooks combinados > Pagamento bem-sucedido do pedido (order_paid)	Ele contém dados de pagamento, detalhes da transação e informações sobre itens comprados. Use os dados do webhook para adicionar itens ao usuário.
Serviços de jogo > Webhooks combinados > Cancelamento de pedidos (order_canceled)	Ele contém dados do pagamento cancelado, detalhes da transação e informações sobre itens comprados. Use os dados do webhook para remover os itens comprados.

Se você receber webhooks separados:

Nome e tipo do webhook	Descrição
Validação de usuário > Validação de usuário (user_validation)	É enviado em diferentes estágios do processo de pagamento para garantir que o usuário esteja registrado no jogo.
Pagamentos > Pagamento (payment)	Ele contém dados de pagamento e detalhes da transação.
Serviços de jogo > Webhooks separados > Pagamento bem-sucedido do pedido (order_paid)	Ele contém informações sobre itens comprados. Use os dados do webhook para adicionar itens ao usuário.
Pagamentos > Reembolso (refund)	Ele contém dados de pagamento e detalhes da transação.
Serviços de jogo > Webhooks separados > Cancelamento de pedidos (order_canceled)	Ele 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.

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

Para gerenciar automaticamente os planos de assinatura, é necessário implementar o processamento dos principais webhooks:

• Validação de usuário (user_validation) — é enviado em diferentes estágios do processo de pagamento para garantir que o usuário esteja registrado no jogo.
• Pagamento (payment) — é enviado quando um pedido é pago e contém dados de pagamento e detalhes da transação.
• Assinatura criada (create_subscription) — é enviado quando um webhook Pagamento foi processado com êxito ou o usuário comprou uma assinatura com um período de avaliação. Ele contém os dados da assinatura comprada e os do usuário. Use os dados do webhook para adicionar uma assinatura ao usuário.
• Assinatura atualizada (update_subscription) — é enviado quando uma assinatura é renovada ou alterada, quando um webhook Pagamento foi processado com êxito. Ele contém os dados da assinatura comprada e os dados do usuário. Use os dados do webhook para estender a assinatura do usuário ou alterar os parâmetros de assinatura.
• Reembolso (refund) — é enviado quando um pedido é cancelado e contém os dados de pagamento cancelados e detalhes da transação.
• Assinatura cancelada (cancel_subscription) — é enviadao quando um webhook Reembolso foi processado com êxito ou a assinatura foi cancelada por outro motivo. Ele contém informações sobre a assinatura e os dados do usuário. Use os dados do webhook para deduzir assinaturas compradas do usuário.

Para habilitar o recebimento de webhooks:

1. No projeto na Conta de Distribuidor, acesse a seção Configurações do Projeto > Webhooks.
2. No campo Servidor de webhooks, especifique o URL do servidor onde você deseja receber webhooks no formato https://example.com. Você também pode especificar o URL encontrado 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 Enable webhooks.

Para desativar o recebimento de webhooks:

1. No projeto na Conta de Distribuidor, acesse a seção Configurações do Projeto > Webhooks.
2. Clique em Desativar webhooks.

As configurações avançadas são disponibilizadas para os webhooks na seção Pagamentos e Loja. Eles aparecerão automaticamente no bloco Configurações gerais depois que você clicar no botão Obter webhooks.

Nesta seção, você pode configurar o recebimento de informações adicionais em webhooks. Para fazer isso, coloque os interruptores correspondentes na posição ativa. A linha de cada permissão indica os webhooks que serão afetados pela alteração das configurações.

Opção	Descrição
Exibir informações sobre a conta de pagamento salva	As informações sobre a forma de pagamento salva são passadas no objeto personalizado payment_account.
Exibir informações sobre transações pelos métodos de pagamento salvos	As informações são passadas nos seguintes parâmetros personalizados do webhook: saved_payment_method: 0 — o método de pagamento guardado não foi utilizado 1 — o método de pagamento foi salvo ao efetuar o pagamento atual 2 — o método de pagamento previamente guardado é utilizado payment_type: 1 — pagamento único 2 — pagamento recorrente
Adicionar objeto de ordem ao webhook	As informações sobre o pedido são passadas no objeto order do webhook Pagamento.
Enviar apenas os parâmetros de usuário necessários sem dados confidenciais	Somente as seguintes informações sobre o usuário são passadas no webhook: ID país
Enviar parâmetros personalizados	As informações sobre os parâmetros de token personalizados são passadas no webhook.
Exibir BIN e sufixo do cartão	As seguintes informações sobre o número do cartão bancário são passadas no webhook: os primeiros 6 dígitos no parâmetro card_bin os últimos 4 dígitos no card_suffix
Exibir marca do cartão	A bandeira do cartão utilizado para efetuar o pagamento. Por exemplo, Mastercard ou Visa.

Testar webhooks ajuda a garantir a configuração correta do projeto tanto do seu lado quanto do lado da Xsolla.

Se os webhooks forem configurados com êxito, uma seção de teste de webhooks será exibida abaixo da seção de configuração de webhooks.

A seção de testes na Conta de Distribuidor varia de acordo com a opção de recebimento do webhook.

Se você receber webhooks combinados:

Nome da aba para testar webhooks	Nome e tipo do webhook
Pagamentos e Loja	Validação de usuário > Validação de usuário (user_validation)
	Serviços de jogo > Webhooks combinados > Pagamento bem-sucedido do pedido (order_paid)
	Serviços de jogo > Webhooks combinados > Cancelamento de pedidos (order_canceled)
Assinaturas	Validação de usuário > Validação de usuário (user_validation)
	Pagamentos > Pagamento (payment)

Se você receber webhooks separados:

Nome da aba para testar webhooks	Nome e tipo do webhook
Loja	Serviços de jogo > Webhooks separados > Pagamento bem-sucedido do pedido (order_paid)
	Serviços de jogo > Webhooks separados > Cancelamento de pedidos (order_canceled)
Pagamentos	Validação de usuário > Validação de usuário (user_validation)
	Pagamentos > Pagamento (payment)
Assinaturas	Validação de usuário > Validação de usuário (user_validation)
	Pagamentos > Pagamento (payment)

O processo de teste para o cenário com webhooks combinados é descrito abaixo.

Na aba Pagamentos e Loja, você pode testar os seguintes webhooks:

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

Para testar:

1. Na seção de teste de webhooks, vá para a aba Pagamentos e Loja.

2. No menu suspenso, selecione o tipo de item. Se o item do tipo selecionado não estiver configurado na Conta de Distribuidor, clique em:

   • Conectar – se o módulo com itens desse tipo não estiver conectado
   • Configurar – se você conectou o módulo anteriormente, mas não concluiu a configuração
     Ao clicar no botão, você será redirecionado para a seção de Conta de Distribuidor correspondente ao tipo do item selecionado. Depois de criar o item, retorne à seção de teste de webhook e prossiga para a próxima etapa.

3. Preencha os campos necessários:

   1. Selecione o SKU dos itens na lista suspensa e indique a quantidade. Você pode escolher vários itens do mesmo tipo clicando em + e adicionando-os em uma nova linha.
   2. ID de Usuário — ao testar, você pode usar qualquer combinação de letras e dígitos.
   3. ID de Usuário Público — ID conhecido por um usuário, como um e-mail ou apelido. Este campo é exibido se o ID de Usuário Público estiver habilitado em seu projeto nas Configurações da Pay Station.
   4. Insira qualquer valor no campo ID do Pedido Xsolla.
   5. ID de Fatura Xsolla — ID da transação no lado da Xsolla. Ao testar, você pode usar qualquer valor numérico.
   6. ID da Fatura — ID da transação no lado do seu jogo. Ao testar, você pode usar qualquer combinação de letras e dígitos. Não é um parâmetro necessário para um pagamento bem-sucedido, mas você pode passá-lo para vincular o ID da transação do seu lado ao ID da transação do lado da Xsolla.
   7. Valor — quantia do pagamento. Ao testar, você pode usar qualquer valor numérico.
   8. Moeda — selecione uma moeda na lista suspensa.

4. Clique em Testar webhooks.

Os webhooks Validação do usuário, Pagamento bem-sucedido do pedido e Cancelamento do 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 do botão Testar webhooks.

Se o ID de usuário público estiver ativado em 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 de ambos os cenários: um bem-sucedido e outro com um erro.

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

• Validação de usuário (user_validation)
• Payment (payment)

Para testar:

1. na seção de testes, vá para a aba Assinaturas.
2. Preencha os campos necessários:

   1. ID de Usuário — ao testar, você pode usar qualquer combinação de letras e dígitos.
   2. ID de Fatura Xsolla — ID da transação no lado Xsolla. Ao testar, você pode usar qualquer valor numérico.
   3. ID de Usuário Público — ID conhecido por um usuário, como um e-mail ou um apelido. Esse campo será exibido se o ID de usuário público estiver habilitado em seu projeto na seção Pay Station > Settings > Additional settings.
   4. Moeda — selecione uma moeda na lista suspensa.
   5. ID do Plano — um plano de assinatura. Escolha um plano na lista suspensa.
   6. Produto de assinatura — escolha um produto na lista suspensa (opcional).
   7. Valor — quantia do pagamento. Ao testar, você pode usar qualquer valor numérico.
   8. ID de Fatura — ID da transação no lado do jogo. Ao testar, você pode usar qualquer combinação de letras e dígitos. Não é um parâmetro necessário para um pagamento bem-sucedido, mas você pode passá-lo para vincular o ID da transação do seu lado ao ID da transação no lado da Xsolla.
   9. Período experimental. Para testar a comp ra de uma assinatura sem um período de avaliação ou para testar a renovação de uma assinatura, especifique o valor 0.
3. Clique em Testar webhooks.

No URL especificado, você receberá webhooks com dados preenchidos. Os resultados do teste de cada webhook, tanto para um cenário bem-sucedido quanto para um cenário com um erro, são exibidos no botão Testar webhooks.

Ouvinte webhook é o código de programa que permite receber webhooks acionados em um endereço URL especificado, gerando uma assinatura e enviando uma resposta para o servidor webhook Xsolla.

No lado do seu aplicativo, implemente a recepção de webhooks dos seguintes endereços IP: 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24, 34.102.38.178, 34.94.43.207, 35.236.73.234, 34.94.69.44, 34.102.22.197.

Limitações:

• Não deve haver várias transações bem-sucedidas com o mesmo ID no banco de dados do aplicativo.
• Se o ouvinte do webhook recebeu um webhook com um ID que já existe no banco de dados, você precisará retornar o resultado do processamento anterior dessa transação. Não é recomendável creditar o usuário com uma compra duplicada e criar registros duplicados no banco de dados.

Ao receber um webhook, você deve garantir a segurança da transmissão de dados. Para conseguir isso, uma assinatura deve ser gerada 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.

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
  "notification_type":"user_validation",
  "user":{
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
  }
}

curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'

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

• Código HTTP '200', '201' ou '204' em caso de resposta bem-sucedida.
• 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 webhooks também pode retornar um código HTTP '5xx' em caso de problemas temporários em seu servidor.

Se o servidor Xsolla não recebeu uma resposta aos webhooks Pagamento bem-sucedido do pedido e Cancelamento do pedido, ou recebeu uma resposta com um código '5xx', os webhooks serão reenviados de acordo com o seguinte agendamento:

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

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

Se o servidor Xsolla não recebeu uma resposta ao webhook Pagamento ou ao webhook Reembolso, ou recebeu uma resposta com um código '5xx', os webhooks também serão reenviados com um intervalo de tempo maior. Um máximo de 12 tentativas são feitas dentro de 12 horas.

Se o servidor Xsolla não recebeu uma resposta ao webhook Validação de usuário ou recebeu uma resposta com um código de '400' ou '5xx', o webhook Validação de usuário não será reenviado. Nesse caso, o usuário vê um erro e os webhooks Pagamento e Pagamento bem-sucedido do pedido não são enviados.

Códigos de erro para o código HTTP 400:

Código	Mensagem
INVALID_USER	Usuário inválido
INVALID_PARAMETER	Parâmetro inválido
INVALID_SIGNATURE	Assinatura inválida
INCORRECT_AMOUNT	Quantia incorreta
INCORRECT_INVOICE	Invoice incorreto

HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

Webhook	Tipo de notificação	Descrição
Validação de usuário	user_validation	Enviado para verificar se um usuário existe no jogo.
Pesquisa de usuário	user_search	Enviado para obter as informações do usuário com base no ID de usuário público.
Pagamento	payment	Enviado quando um usuário conclui um pagamento.
Reembolso	refund	Enviado quando um pagamento precisa ser cancelado por qualquer motivo.
Reembolso parcial	partial_refund	Enviado quando um pagamento deve ser parcialmente cancelado por qualquer motivo.
Transação rejeitada pelo AFS	afs_reject	Enviado quando uma transação é recusada durante uma verificação AFS.
Lista de bloqueios atualizada do AFS	afs_black_list	Enviado quando a lista de bloqueio do AFS é atualizada.
Assinatura criada	create_subscription	Enviado quando um usuário cria uma assinatura.
Assinatura atualizada	update_subscription	Enviado quando uma assinatura é renovada ou alterada.
Assinatura cancelada	cancel_subscription	Enviado quando uma assinatura é cancelada.
Assinatura não renovável	non_renewal_subscription	Enviado quando o status é definido como não renovável.
Adicionar conta de pagamento	payment_account_add	Enviado quando um usuário adiciona ou salva uma conta de pagamento.
Remover conta de pagamento	payment_account_remove	Enviado quando um usuário remove a conta de pagamento das contas salvas.
Validação de usuário na Web Shop	-	Enviado de um site Web Shop para verificar se um usuário existe no jogo.
Personalização de catálogo no lado do parceiro	partner_side_catalog	Enviado quando um usuário interage com a loja.
Pagamento bem-sucedido do pedido	order_paid	Enviado quando um pedido é pago.
Cancelamento do pedido	order_canceled	Enviado quando um pedido é cancelado.
Disputa	dispute	Enviado quando uma nova disputa é aberta.