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:

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.
Botão Comprar	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	Para receber 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	Opcional	Para a 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	Opcional	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. Você pode aprender mais nas instruções de configuração de webhooks para o Digital Distribution Hub.

Se você usa produtos e soluções que exijam 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.

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

• User validation (user_validation) — é enviado em diferentes estágios do processo de pagamento para garantir que o usuário esteja registrado no jogo.
• Payment (payment) — é enviado quando um pedido é pago e contém dados de pagamento e detalhes da transação.
• Successful payment of the order (order_paid) — é enviado quando um webhook Payment foi 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 (refund) — é enviado quando um pedido é cancelado e contém os dados de pagamento cancelados e detalhes da transação.
• Order cancellation (order_canceled) — é 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.

Se a personalização do catálogo de itens for implementada no lado do aplicativo, configure o processamento do webhook Catalog personalization on the partner’s side.

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

• User validation (user_validation) — é enviado em diferentes estágios do processo de pagamento para garantir que o usuário esteja registrado no jogo.
• Payment (payment) — é enviado quando um pedido é pago e contém dados de pagamento e detalhes da transação.
• Created subscription (create_subscription) — é enviado quando um webhook Payment 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.
• Updated subscription (update_subscription) — é enviado quando uma assinatura é renovada ou alterada, quando um webhook Payment 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.
• Refund (refund) — é enviado quando um pedido é cancelado e contém os dados de pagamento cancelados e detalhes da transação.
• Canceled subscription (cancel_subscription) — é enviadao quando um webhook Refund 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. 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 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.
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 Enable webhooks.

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 Desativar webhooks.

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

Você pode testar o recebimento dos seguintes webhooks:

Nome do webhook	Tipo de webhook
Validação do usuário	user_validation
Pagamento	payment
Cancelamento do pedido	order_canceled
Pagamento bem-sucedido do pedido	order_paid

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.

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

• 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 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:
   • Connect – se o módulo com itens desse tipo não estiver conectado
   • Configure – 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. Insira qualquer valor no campo ID do Pedido Xsolla.
4. Selecione o SKU dos itens na lista suspensa e indique o valor. Você pode escolher vários itens do mesmo tipo clicando em + e adicionando-os em uma nova linha.
5. Escolha a moeda em que o pedido será pago.
6. Clique em Test.

Os 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 do botão Test webhooks.

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

• User validation (user_validation)
• Payment (payment)

Para testar:

1. Na seção de testes, vá para a aba Paymenys.
2. Preencha os campos necessários:
   1. User ID — ao testar, você pode usar qualquer combinação de letras e dígitos.
   2. Public user ID — 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.
   3. Currency — selecione uma moeda na lista suspensa.
   4. Xsolla Invoice ID — ID da transação no lado Xsolla. Ao testar, você pode usar qualquer valor numérico.
   5. Amount — quantia do pagamento. Ao testar, você pode usar qualquer valor numérico.
   6. Invoice ID — 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.
3. Clique em Test 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 Test webhooks. Se o ID de usuário público estiver habilitado 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.

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 em 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.

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 Payment .
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.

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

• User validation (user_validation)
• Payment (payment)

Para testar:

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

   1. User ID — ao testar, você pode usar qualquer combinação de letras e dígitos.
   2. Xsolla Invoice ID — ID da transação no lado Xsolla. Ao testar, você pode usar qualquer valor numérico.
   3. Public user ID — 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. Currency — selecione uma moeda na lista suspensa.
   5. Plan ID — um plano de assinatura. Escolha um plano na lista suspensa.
   6. Produto de subscription — escolha um produto na lista suspensa (opcional).
   7. Amount — quantia do pagamento. Ao testar, você pode usar qualquer valor numérico.
   8. Invoice ID — 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 Test 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 Test 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, 35.236.90.90, 34.102.38.178.

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 uma resposta não for recebida para os webhooks Successful payment of the order e Order cancellation do pedido ou se uma resposta com um código '5xx' foi recebida, os webhooks são reenviados de acordo com o seguinte cronograma:

• 2 tentativas com intervalo de 5 minutos
• 7 tentativas com 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 foi recebida nem no webhook Payment, nem no webhook Refund, ou se uma resposta com um código '5xx' foi recebida, os webhooks também são reenviados com um intervalo de tempo maior. Há um limite de 12 tentativas dentro de 12 horas.

Se uma resposta não foi recebida para o webhook User validation ou uma resposta com um código de '400' ou '5xx' foi recebida, o webhook User validation não é reenviado. Nesse caso, um erro é mostrado ao usuário e os webhooks Payment e Successful payment of the order 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 do usuário	user_validation	Enviado para verificar se um usuário existe no jogo.
Pesquisa do 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.