Webhook

Através deste recurso, você pode receber uma notificação quando um evento específico ocorrer.

Como, por exemplo, quando um pedido tiver seu pagamento confirmado.

Eventos Disponíveis 🗓️

Para obter os eventos disponíveis, faça uma GET para:

/webhook/eventos/

Será retornado todos os eventos disponíveis e quais informações serão enviadas:

[
  {
    "Codigo": "Pedidos_Concluidos",
    "Titulo": "Pedidos que foram marcados como Concluído/Entregue"
  }
]

Nestes eventos, o que iremos utilizar para configurar o webhook é o "Codigo", que represente o evento que será enviado.

No caso de Pedidos com pagamento confirmado, o evento é:

Pedidos_Pagos

Configurando Webhook ⚙️

Para criar um webhook, faça um POST para:

/webhook/

Neste POST, precisamos enviar:

Evento

O Código do Evento, que obtemos na API "/webhook/eventos/".

É possível configurar um webhook para cada evento.

Endpoint

A Url para qual será enviado as notificações.

Exemplo:

https://webhook.site/34bde777-5d3d-4591-b0c8-36a1e729753b

Esta Url deve possuir alguns requisitos:

• Possuir SSL

• Permitir receber POST no formato JSON

• Retornar um HttpCode 200

Exemplo de POST:

{
  "Evento": "Pedidos_Pagos",
  "Endpoint": "https://webhook.site/34bde777-5d3d-4591-b0c8-36a1e729753b"
}

O retorno será o código do webhook, para permitir editar o endpoint e remover o webhook:

{
  "Codigo": 6
}

Dados Enviados 📤

Quando um webhook é disparado, nosso sistema envia os dados do evento e o endpoint de onde pode ser obtido detalhes do evento:

{
  "Evento": "Pedidos_Criados",
  "Data": "2025-07-22 10:21:15",
  "Recurso": "/pedidos/999999/",
  "Tentativa": 1,
  "Dados": {
    "CodigoPedido": 999999
  }
}

Nestes dados, temos:

Evento

Evento que está sendo disparado

Data

Data em que o evento de notificação foi iniciado, caso ocorram mais tentativas, esta data não muda

Recurso

Endpoint que pode ser utilizado para obter os dados completos deste registro.

Caso não seja retornado um "Recurso", indica que a informação não esta disponível nos Endpoints de nossa API, neste caso, todos os dados serão retornados em "Dados".

Tentativa

Tentativa desta requisição (limitando-se a 3 tentativas)

Dados

Dados relacionados a esta notificação.

No caso de Pedidos, será sempre enviado o Código do Pedido, que pode ser utilizado nos endpoints /pedidos/.

Exemplo de cada evento:

Pedidos_Concluidos

Pedidos que já foram Entregues e Concluídos:

{
  "Evento": "Pedidos_Concluidos",
  "Data": "2025-07-22 12:09:55",
  "Recurso": "/pedidos/999999/",
  "Tentativa": 1,
  "Dados": {
    "CodigoPedido": 999999
  }
}

Pedidos_Enviados

Pedidos Enviados ou Reenviados:

{
  "Evento": "Pedidos_Enviados",
  "Data": "2025-07-22 12:09:50",
  "Recurso": "/pedidos/999999/",
  "Tentativa": 1,
  "Dados": {
    "CodigoPedido": 999999
  }
}

Pedidos_Pagos

Pedidos com Pagamento Confirmado (Mesmo não estando Capturado - Para os casos de Captura Manual):

{
  "Evento": "Pedidos_Pagos",
  "Data": "2025-07-22 12:09:36",
  "Recurso": "/pedidos/999999/",
  "Tentativa": 1,
  "Dados": {
    "CodigoPedido": 999999
  }
}

Pedidos_Criados

Momento inicial do Pedido, quando o pedido é efetivado (é normalmente o momento em que o cliente está realizando o pagamento):

{
  "Evento": "Pedidos_Criados",
  "Data": "2025-07-22 12:09:23",
  "Recurso": "/pedidos/999999/",
  "Tentativa": 1,
  "Dados": {
    "CodigoPedido": 999999
  }
}

Pedidos_Todos

Evento enviado quando qualquer alteração de status for realizada em um pedido:

{
  "Evento": "Pedidos_Todos",
  "Data": "2025-07-22 12:09:36",
  "Recurso": "/pedidos/999999/",
  "Tentativa": 1,
  "Dados": {
    "CodigoPedido": 999999
  }
}

Clientes_Cadastro

Cadastro de novos Clientes:

{
  "Evento": "Clientes_Cadastro",
  "Data": "2025-07-22 12:08:33",
  "Recurso": "/clientes/999999/",
  "Tentativa": 1,
  "Dados": {
    "CodigoCliente": 999999
  }
}

Clientes_Edicao

Edição do cliente realizado pelo próprio cliente e/ou pela administração:

{
  "Evento": "Clientes_Edicao",
  "Data": "2025-07-22 12:09:02",
  "Recurso": "/clientes/999999/",
  "Tentativa": 1,
  "Dados": {
    "CodigoCliente": 999999
  }
}

Tentativas 🔁

O sistema ira tentar enviar a notificação por 3 vezes, em intervalos de 10 minutos.

No envio dos dados, será enviado o elemento "Tentativa" indicando qual a tentativa está sendo enviada neste instante.

Sucesso ✅

O sistema ira entender que a notificação foi enviada com sucesso, quando o webhook nos retornar um HTTPCODE 200.

Qualquer outra HTTPCODE será entendido como FALHA.

Validando Webhook 🕵️‍♂️

Para garantir que o Webhook foi enviado pelo Toplojas, enviamos no Header da requisição a API KEY da Loja:

{
  "x-webhook-api-key": "XXXXXXXXXXXXXXXX"
}

Desta forma, você pode validar a notificação, garantindo que ela não veio de fontes não confiáveis.

Firewall 🧱

Caso você tenha um firewall em seu servidor, é importante garantir que o IP de nosso servidor de notificações esteja em sua lista branca.

Para isto, adicione o IP abaixo em sua lista branca:

177.136.232.132

É importante, também, garantir que o UserAgent, utilizado nas requisições de nosso servidor, não seja bloqueado pelo seu servidor.

Para isto, garanta que o UserAgent abaixo não seja bloqueado:

Toplojas (+https://www.toplojas.com.br/)

Mais Detalhes 🔍

Para obter detalhes completos dos endpoints relacionados ao módulo de Webhook, clique no link abaixo e consulte nossa documentação completa:

Swagger UIapi.toplojas.com.br