# 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="" %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://apidoc.toplojas.com.br/funcionamento/webhook.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.