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 operar plenamente uma loja no jogo, é necessário implementar o processamento dos principais webhooks:
- 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 Pagamento é 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 — é 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. Use os dados do webhook para remover os itens comprados.
User validation — é enviado em diferentes estágios do processo de pagamento para garantir que o usuário esteja cadastrado no jogo.
Abaixo, temos um esquema de compra e devolução de produtos no site usando webhooks desta lista.
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:
- Abra seu projeto na Conta de Distribuidor.
- Clique em Project settings no menu lateral e vá para a aba Webhooks.
- 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. - É 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.
- Clique em Enable webhooks.
- Abra seu projeto na Conta de Distribuidor.
- Clique em Project settings no menu lateral e vá para a aba Webhooks.
- Clique em Disable webhooks.
Teste de webhooks na Conta de Distribuidor
Você pode testar o recebimento dos seguintes webhooks:
Nome do webhook | Tipo de webhook |
---|---|
Validação do usuário | user_validation |
Pagamento | payment |
Cancelamento de pedido | order_canceled |
Successful payment of the order | order_paid |
Se os webhooks forem configurados com êxito, um bloco de teste de webhook será exibido abaixo do bloco de configuração do webhook.
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:
- Concatene o JSON do corpo da solicitação e da chave secreta do projeto.
- 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
ou204
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.
Encontrou um erro de texto ou digitação? Selecione o texto e pressione Ctrl+Enter.