# 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: ```json [ { "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:** ** Esta Url deve possuir alguns requisitos: * Possuir **SSL** * Permitir receber **POST** no formato **JSON** * Retornar um HttpCode **200**
**Exemplo de POST:** ```json { "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: ```json { "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: ```json { "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**: ```json { "Evento": "Pedidos_Concluidos", "Data": "2025-07-22 12:09:55", "Recurso": "/pedidos/999999/", "Tentativa": 1, "Dados": { "CodigoPedido": 999999 } } ```
Pedidos_Enviados Pedidos **Enviados** ou **Reenviados**: ```json { "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*): ```json { "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*): ```json { "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: ```json { "Evento": "Pedidos_Todos", "Data": "2025-07-22 12:09:36", "Recurso": "/pedidos/999999/", "Tentativa": 1, "Dados": { "CodigoPedido": 999999 } } ```
Clientes_Cadastro Cadastro de novos Clientes: ```json { "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: ```json { "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: ```json { "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: {% embed url="" %}