Webhooks permitem que você receba notificações instantâneas de eventos configurados que acontecem no lado da Xsolla. Você pode usar webhooks para automatizar funções complementares e de back-end do seu aplicativo.

Exemplos de eventos sobre os quais você pode ser notificado:

• pagamentos, incluindo compras de moedas virtuais e itens
• pagamentos recorrentes e ações com assinaturas
• reembolsos

Quando um evento pré-definido ocorre, a Xsolla notifica seu sistema por meio de webhooks. Como exemplo, você poderá executar as seguintes ações depois de receber um webhook:

• adicionar ao saldo de um usuário
• desbloquear novos itens para um usuário
• iniciar serviço de assinatura
• bloquear usuário após a detecção de fraude

Abaixo temos um exemplo de como um webhook de processamento de pagamento funciona:

As seguintes configurações devem ser aplicadas para que os webhooks funcionem corretamente:

• Ouça webhooks nos seguintes endereços IP: 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24.
• O banco de dados do aplicativo não deve conter duas transações bem-sucedidas com o mesmo ID.

• Uma assinatura criada deve corresponder àquela passada no cabeçalho HTTP.
• Em caso de erro, retorne o código 400 (exemplo: quando um parâmetro necessário estiver ausente ou uma recarga falhar). Para erros temporários com os servidores, use o código 500.

Como as conexões com a internet nem sempre são 100% confiáveis, os webhooks podem ser perdidos ou atrasados. Para resolver esse problema, a Xsolla reenvia webhooks com falha até que o ouvinte os receba. Os reenvios de webhook são enviados dentro de 12 horas após o anterior até que o ouvinte confirme o recebimento. O número máximo de tentativas é 12.

As assinaturas digitais permitem a transmissão segura de dados. Para gerar uma assinatura:

1. Concatene o corpo JSON da solicitação com a chave secreta do seu projeto.
2. Aplique o hash SHA-1 à string resultante.

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"
      }
    }'

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"
    }
}