Autenticação de Webhook

Dados da API

API Gateway
Esta API é utilizada para operações do gateway de pagamento:

• Produção: https://api.sopague.com.br/gateway
• Homologação: https://api-hmg.sopague.com.br/gateway
• Arquitetura: Representational State Transfer (REST)

Descrição

Endpoints responsáveis por gerenciar credenciais de autenticação "Basic" utilizadas pelo serviço de Webhook.

O sistema já envia o cabeçalho Access-Key para identificação do remetente, e agora permite que o cliente cadastre ou remova uma autenticação "Basic" adicional, que será incluída automaticamente no header das requisições do webhook.

Webhook Automático

Quando um pagamento é processado, nossa plataforma automaticamente envia uma notificação para sua aplicação com os dados da transação. A autenticação "Basic" adiciona uma camada extra de segurança para essas notificações.

Saiba mais sobre Webhooks →

🔐 Endpoints

➕ Cadastrar Autenticação de Webhook

POST /v1/security/webhook-auth

Cadastra uma autenticação "Basic" que será incluída automaticamente no header das requisições de webhook.

Requisição

{
  "basic": "Basic <Base64>"
}

Dicionário de dados - Parâmetros

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO	VALIDAÇÃO
basic	Credencial de autenticação Basic no formato "Basic <Base64>"	String	Body	sim	Deve iniciar com "Basic " e conter Base64 válido

Regras de validação

• O campo basic é obrigatório

• Deve iniciar com "Basic "

• O conteúdo após "Basic " deve ser um Base64 válido

• É permitido apenas um cadastro ativo por cliente

  🟢 201

  Autenticação cadastrada com sucesso

  {
    "message": "Autenticação de webhook cadastrada com sucesso"
  }

  Dicionário de dados - Retorno

  PROPRIEDADE	DESCRIÇÃO	TIPO
  message	Mensagem de sucesso	string

  🔴 400

  Erro de validação

  [
    {
      "tag": "basic",
      "description": "Campo basic é obrigatório"
    }
  ]

  Possíveis erros de validação

  ERRO	DESCRIÇÃO
  Campo basic é obrigatório	O campo basic não foi informado
  Formato inválido	O campo basic deve iniciar com "Basic "
  Base64 inválido	O conteúdo após "Basic " deve ser um Base64 válido
  Já existe autenticação	Credenciais já cadastradas para este cliente

  🔴 401

  Acesso não autorizado

  [
    {
      "tag": "unauthorized",
      "description": "MID inválido ou inexistente"
    }
  ]

  🔴 500

  Erro interno

  [
    {
      "tag": "internal_error",
      "description": "Não foi possível executar comando. Erro desconhecido."
    }
  ]

➖ Excluir Autenticação de Webhook

DELETE /v1/security/webhook-auth

Remove a autenticação "Basic" cadastrada para o cliente.

Requisição

// Não requer body na requisição

🟢 201

Autenticação removida com sucesso

{
  "message": "Autenticação de webhook removida com sucesso"
}

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
message	Mensagem de sucesso	string

🔴 401

Acesso não autorizado

[
  {
    "tag": "unauthorized",
    "description": "MID inválido ou inexistente"
  }
]

🔴 500

Erro interno

[
  {
    "tag": "internal_error",
    "description": "Não foi possível executar comando. Erro desconhecido."
  }
]

Headers HTTP

As requisições para os endpoints de autenticação de webhook exigem autenticação Bearer no header:

Content-Type: application/json
Authorization: Bearer <token>

---

Consulte também

Códigos de Resposta

Em caso de falha na transação, consulte nossa tabela completa de códigos de resposta para identificar e tratar adequadamente os erros:

Códigos de Resposta do Host →

Webhooks

Para entender como funcionam as notificações webhook e como implementar o recebimento em sua aplicação:

Notificações Webhook →