Documentação de Webhooks
Introdução
Os webhooks permitem que sua aplicação receba notificações em tempo real sobre eventos que ocorrem em nossa plataforma. Este documento descreve os diferentes tipos de eventos disponíveis, a estrutura das notificações e como implementar um endpoint para receber esses webhooks.
Conceitos Básicos
Um webhook é uma notificação HTTP POST enviada para um URL configurado em sua aplicação sempre que um evento ocorre em nosso sistema. O corpo da requisição contém informações detalhadas sobre o evento em formato JSON.
Configuração
Para configurar webhooks em sua aplicação:
- Acesse o painel de administração
- Navegue até Configurações > Integrações > Webhooks
- Adicione a URL de destino para onde as notificações serão enviadas
- Selecione os eventos que deseja monitorar
- Salve suas configurações
Segurança
Cada webhook inclui um token único no payload que pode ser usado para verificar a autenticidade da notificação. Recomendamos que você valide este token antes de processar o webhook.
Tipos de Eventos
Nossa plataforma suporta os seguintes tipos de eventos:
| Código | Descrição | Categoria |
|---|---|---|
| 1 | Cliente Cadastrado | Cliente |
| 2 | Cliente Alterado | Cliente |
| 3 | Abandono de Checkout | Pedido |
| 4 | Aguardando Pagamento | Pedido |
| 5 | Compra Aprovada | Pedido |
| 6 | Compra Cancelada | Pedido |
| 10 | Produto Cadastrado | Produto |
| 11 | Produto Alterado | Produto |
Estrutura de Dados
Todos os webhooks possuem a seguinte estrutura básica:
json
{
"date": "YYYY-MM-DD HH:MM:SS",
"eventType": {
"token": "string",
"code": number,
"description": "string"
},
// Dados específicos do evento...
}Eventos de Cliente (Códigos 1 e 2)
Quando um cliente é cadastrado ou alterado, o webhook inclui os seguintes dados:
json
{
"date": "2025-03-01 22:06:59",
"eventType": {
"token": "60039c82798d7",
"code": 1,
"description": "Cliente Cadastrado"
},
"shopper": {
"id": 4347,
"id_store": 1,
"name": "Nome do Cliente",
"email": "[email protected]",
"phone": "99999999999",
"phone_ddd": "99",
"cpf_cnpj": null,
"instagram": null,
"link": null,
"tags": null,
"active": true
}
}Eventos de Pedido (Códigos 3, 4, 5 e 6)
Eventos relacionados a pedidos incluem informações detalhadas sobre o pedido e o cliente:
json
{
"date": "2025-03-01 21:16:13",
"eventType": {
"token": "60039c82798d7",
"code": 4,
"description": "Aguardando Pagamento"
},
"shopper": {
"id": "4323",
"id_store": "1",
"name": "Nome do Cliente",
"email": "[email protected]",
"phone": "99999999999",
"phone_ddd": "99",
"cpf_cnpj": null,
"instagram": null,
"link": null,
"tags": null,
"active": "1"
},
"order": {
"id": "3552",
"id_store": "1",
"id_store_coupon": null,
"amount": "320.97",
"discount": "116.93",
"fee_tax": "9.00",
"exchange": "",
"payment": "4",
"shipping": "entrega",
"name": "Nome do Cliente",
"phone": "99999999999",
"email": "[email protected]",
"cpf_cnpj": "",
"zip": "31210-030",
"address": "Rua Exemplo",
"number": "123",
"complement": "",
"district": "Bairro",
"city": "Cidade",
"state": "UF",
"status": "1",
"status_order": "1",
"created_at": "2025-02-11 22:56:18",
"items": [
{
"id": "24489",
"id_order": "3552",
"id_product": "11526",
"id_variation": null,
"id_variation_item": null,
"code": "1123",
"ean": null,
"name": "Nome do Produto",
"price": "29.90",
"category": "Categoria",
"quantity": "1"
}
]
}
}Eventos de Produto (Códigos 10 e 11)
Quando um produto é cadastrado ou alterado, o webhook inclui:
json
{
"date": "2025-03-01 23:26:58",
"eventType": {
"token": "60039c82798d7",
"code": 10,
"description": "Produto Cadastrado"
},
"product": {
"code": null,
"promo_start": null,
"promo_end": null,
"external_link": null,
"id_user_updated": "1",
"name": "Nome do Produto",
"price": 99.99,
"price_promo": null,
"category": "Categoria",
"category_id": "707",
"description_small": "Descrição curta",
"description": "{\"title\":\"Título do produto\",\"image\":\"assets\\/img\\/product-default.png\",\"text\":\"Descrição detalhada\"}",
"variation": 0,
"active": 1,
"highlight": 0,
"stock": 14,
"id_store": "1",
"id_user": "1",
"uniqid": "67c3c1f282a09",
"uri": "nome-do-produto"
}
}Exemplos Detalhados por Evento
1. Cliente Cadastrado
Este evento é disparado quando um novo cliente é registrado na plataforma.
Exemplo de payload:
json
{
"date": "2025-03-01 22:06:59",
"eventType": {
"token": "60039c82798d7",
"code": 1,
"description": "Cliente Cadastrado"
},
"shopper": {
"id": 4347,
"id_store": 1,
"name": "Almerita Goes",
"email": "[email protected]",
"phone": "31938389393",
"phone_ddd": "31",
"cpf_cnpj": null,
"instagram": null,
"link": null,
"tags": null,
"active": true
}
}2. Cliente Alterado
Este evento é disparado quando as informações de um cliente existente são atualizadas.
Exemplo de payload:
json
{
"date": "2024-09-22 10:21:24",
"eventType": {
"code": 2,
"description": "Cliente Alterado"
},
"shopper": {
"id": 3373,
"id_store": 1,
"name": "João Matos",
"email": "[email protected]",
"phone": "12312312312",
"phone_ddd": "12",
"cpf_cnpj": null,
"instagram": null,
"link": null,
"tags": null,
"active": true
}
}3. Abandono de Checkout
Este evento é disparado quando um cliente inicia o processo de checkout mas não finaliza a compra.
Exemplo de payload:
json
{
"date": "2024-09-22 10:21:24",
"eventType": {
"code": 3,
"description": "Abandono de Checkout"
},
"shopper": {
"id": 3373,
"id_store": 1,
"name": "João Matos",
"email": "[email protected]",
"phone": "12312312312",
"phone_ddd": "12",
"cpf_cnpj": null,
"instagram": null,
"link": null,
"tags": null,
"active": true
},
"cart":{
"id_store":"1",
"amount":"77.77",
"payment":"3",
"status":"2",
"created_at":"2025-03-02 00:54:42",
"items":[
{
"id":"14137",
"id_cart":"2633",
"id_product":"168998",
"id_variation":"402380",
"id_variation_item":"143912",
"price":"11.11",
"price_promo":null,
"quantity":"7",
"created_at":"2025-03-02 00:54:42"
}
]
}
}4. Aguardando Pagamento
Este evento é disparado quando um pedido é criado e está aguardando confirmação de pagamento.
Exemplo de payload:
json
{
"date": "2025-03-01 21:16:13",
"eventType": {
"token": "60039c82798d7",
"code": 4,
"description": "Aguardando Pagamento"
},
"shopper": {
"id": "4323",
"id_store": "1",
"name": "joao da asilva",
"email": "[email protected]",
"phone": "13213213213",
"phone_ddd": "13",
"cpf_cnpj": null,
"instagram": null,
"link": null,
"tags": null,
"active": "1"
},
"order": {
"id": "3552",
"id_store": "1",
"id_store_coupon": null,
"amount": "320.97",
"discount": "116.93",
"fee_tax": "9.00",
"exchange": "",
"payment": "4",
"shipping": "entrega",
"name": "joao da asilva",
"phone": "13213213213",
"email": "[email protected]",
"cpf_cnpj": "",
"zip": "31210-030",
"address": "Rua Itapecerica",
"number": "123",
"complement": "",
"district": "Lagoinha",
"city": "Belo Horizonte",
"state": "MG",
"status": "1",
"status_order": "1",
"created_at": "2025-02-11 22:56:18",
"items": [
{
"id": "24489",
"id_order": "3552",
"id_product": "11526",
"id_variation": null,
"id_variation_item": null,
"code": "1123",
"ean": null,
"name": "Jaqueta de Couro",
"price": "29.90",
"category": "Outros",
"quantity": "1"
},
{
"id": "24490",
"id_order": "3552",
"id_product": "11479",
"id_variation": null,
"id_variation_item": null,
"code": "12311",
"ean": null,
"name": "Prancha de surf",
"price": "297.00",
"category": "Outros",
"quantity": "1"
}
]
}
}5. Compra Aprovada
Este evento é disparado quando o pagamento de um pedido é aprovado.
Exemplo de payload:
json
{
"date": "2025-03-01 21:16:12",
"eventType": {
"token": "6021615c89413",
"code": 5,
"description": "Compra Aprovada"
},
"shopper": {
"id": "2565",
"id_store": "83",
"name": "Microcell BR",
"email": "[email protected]",
"phone": "31973493022",
"phone_ddd": "31",
"cpf_cnpj": null,
"instagram": null,
"link": null,
"tags": null,
"active": "1"
},
"order": {
"id": "1490",
"id_store": "83",
"id_store_coupon": null,
"amount": "949.50",
"discount": "0.00",
"fee_tax": null,
"exchange": "1111",
"payment": "3",
"shipping": "",
"name": "Microcell BR",
"phone": "31973493022",
"email": "[email protected]",
"cpf_cnpj": "",
"zip": "",
"address": "",
"number": "",
"complement": "",
"district": "",
"city": "",
"state": "",
"status": "2",
"status_order": "1",
"created_at": "2023-12-04 22:45:33",
"items": [
{
"id": "9173",
"id_order": "1490",
"id_product": "169116",
"id_variation": "406535",
"id_variation_item": "160131",
"code": "13259",
"ean": null,
"name": "Vestido Ofélia - Off White - G",
"price": "189.90",
"category": "Vestido",
"quantity": "4"
},
{
"id": "9174",
"id_order": "1490",
"id_product": "169116",
"id_variation": "406535",
"id_variation_item": "160129",
"code": "13259",
"ean": null,
"name": "Vestido Ofélia - Off White - P",
"price": "189.90",
"category": "Vestido",
"quantity": "1"
}
]
}
}6. Compra Cancelada
Este evento é disparado quando um pedido é cancelado.
Exemplo de payload:
json
{
"date": "2025-03-01 20:58:59",
"eventType": {
"token": "6021615c89413",
"code": 6,
"description": "Compra Cancelada"
},
"shopper": {
"id": "2442",
"id_store": "83",
"name": "joao da silva",
"email": "[email protected]",
"phone": "31973493022",
"phone_ddd": "31",
"cpf_cnpj": null,
"instagram": null,
"link": null,
"tags": null,
"active": "1"
},
"order": {
"id": "1275",
"id_store": "83",
"id_store_coupon": null,
"amount": "959.20",
"discount": "0.00",
"fee_tax": null,
"exchange": "",
"payment": "1",
"shipping": "",
"name": "joao da silva",
"phone": "31973493022",
"email": "[email protected]",
"cpf_cnpj": "",
"zip": "",
"address": "",
"number": "",
"complement": "",
"district": "",
"city": "",
"state": "",
"status": "3",
"status_order": "1",
"created_at": "2023-10-23 06:52:18",
"items": [
{
"id": "8021",
"id_order": "1275",
"id_product": "169118",
"id_variation": "406541",
"id_variation_item": "160149",
"code": "06282",
"ean": null,
"name": "Blusa Lorelay - Off White - G",
"price": "119.90",
"category": "Blusa",
"quantity": "1"
},
{
"id": "8022",
"id_order": "1275",
"id_product": "169118",
"id_variation": "406541",
"id_variation_item": "160147",
"code": "06282",
"ean": null,
"name": "Blusa Lorelay - Off White - P",
"price": "119.90",
"category": "Blusa",
"quantity": "7"
}
]
}
}10. Produto Cadastrado
Este evento é disparado quando um novo produto é criado na plataforma.
Exemplo de payload:
json
{
"date": "2025-03-01 23:26:58",
"eventType": {
"token": "60039c82798d7",
"code": 10,
"description": "Produto Cadastrado"
},
"product": {
"code": null,
"promo_start": null,
"promo_end": null,
"external_link": null,
"id_user_updated": "1",
"name": "novo produto rapido",
"price": 22.22,
"price_promo": null,
"category": "Camisetas",
"category_id": "707",
"description_small": "novo produto rapido",
"description": "{\"title\":\"novo produto rapido\",\"image\":\"assets\\/img\\/product-default.png\",\"text\":\"descrição do novo prod\"}",
"variation": 0,
"active": 1,
"highlight": 0,
"stock": 14,
"id_store": "1",
"id_user": "1",
"uniqid": "67c3c1f282a09",
"uri": "novo-produto-rapido"
}
}11. Produto Alterado
Este evento é disparado quando as informações de um produto são atualizadas.
Exemplo de payload:
json
{
"date": "2025-03-01 23:26:15",
"eventType": {
"token": "60039c82798d7",
"code": 11,
"description": "Produto Alterado"
},
"product": {
"code": null,
"promo_start": null,
"promo_end": null,
"external_link": null,
"id_user_updated": "1",
"name": "Novo Prod do nada22",
"price": 111.11,
"price_promo": null,
"category": "OLYA",
"category_id": "732",
"description_small": "Novo Prod do nada22",
"description": "{\"title\":\"Novo Prod do nada22\",\"image\":\"assets\\/img\\/product-default.png\",\"text\":\"vai\"}",
"variation": 0,
"active": 1,
"highlight": 0,
"stock": 14
}
}Referência de Códigos e Status
Códigos de Evento
| Código | Descrição |
|---|---|
| 1 | Cliente Cadastrado |
| 2 | Cliente Alterado |
| 3 | Abandono de Checkout |
| 4 | Aguardando Pagamento |
| 5 | Compra Aprovada |
| 6 | Compra Cancelada |
| 10 | Produto Cadastrado |
| 11 | Produto Alterado |
Códigos de Status de Pedido
| Código | Descrição |
|---|---|
| 1 | Aguardando Pagamento |
| 2 | Pedido Aprovado |
| 3 | Pedido Cancelado |
| 4 | Pedido Enviado |
| 5 | Pedido Entregue |
Códigos de Pagamento
| Código | Descrição |
|---|---|
| 1 | Boleto Bancário |
| 2 | Cartão de Crédito |
| 3 | Transferência Bancária |
| 4 | PIX |
Implementação
Exemplo de Endpoint para Receber Webhooks (PHP)
php
<?php
// Recebe o JSON enviado via POST
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);
// Verifica se o JSON é válido
if ($data === null) {
http_response_code(400);
echo json_encode(['error' => 'Invalid JSON payload']);
exit;
}
// Verifica o tipo de evento
$eventCode = $data['eventType']['code'] ?? null;
$eventToken = $data['eventType']['token'] ?? '';
// Valida o token (exemplo simplificado)
$validToken = '60039c82798d7'; // Substitua por seu método de validação
if ($eventToken !== $validToken) {
http_response_code(401);
echo json_encode(['error' => 'Invalid token']);
exit;
}
// Processa o evento com base no código
switch ($eventCode) {
case 1: // Cliente Cadastrado
// Seu código para processar cliente cadastrado
processNewCustomer($data);
break;
case 5: // Compra Aprovada
// Seu código para processar compra aprovada
processApprovedOrder($data);
break;
// ... outros casos
default:
// Evento desconhecido
http_response_code(400);
echo json_encode(['error' => 'Unknown event type']);
exit;
}
// Responde com sucesso
http_response_code(200);
echo json_encode(['status' => 'success']);
// Funções de processamento
function processNewCustomer($data) {
// Implementação do processamento de cliente cadastrado
// Exemplo: salvar em banco de dados, enviar e-mail de boas-vindas, etc.
}
function processApprovedOrder($data) {
// Implementação do processamento de compra aprovada
// Exemplo: atualizar estoque, enviar e-mail de confirmação, etc.
}
?>Exemplo de Endpoint para Receber Webhooks (Node.js)
javascript
const express = require('express');
const app = express();
app.use(express.json());
// Rota para receber webhooks
app.post('/webhooks', (req, res) => {
const data = req.body;
// Verifica se o payload é válido
if (!data || !data.eventType || !data.eventType.code) {
return res.status(400).json({ error: 'Invalid payload' });
}
// Valida o token (exemplo simplificado)
const eventToken = data.eventType.token || '';
const validToken = '60039c82798d7'; // Substitua por seu método de validação
if (eventToken !== validToken) {
return res.status(401).json({ error: 'Invalid token' });
}
// Processa o evento com base no código
const eventCode = data.eventType.code;
switch (eventCode) {
case 1: // Cliente Cadastrado
processNewCustomer(data);
break;
case 5: // Compra Aprovada
processApprovedOrder(data);
break;
// ... outros casos
default:
return res.status(400).json({ error: 'Unknown event type' });
}
// Responde com sucesso
return res.status(200).json({ status: 'success' });
});
// Funções de processamento
function processNewCustomer(data) {
// Implementação do processamento de cliente cadastrado
// Exemplo: salvar em banco de dados, enviar e-mail de boas-vindas, etc.
console.log('Novo cliente:', data.shopper.name);
}
function processApprovedOrder(data) {
// Implementação do processamento de compra aprovada
// Exemplo: atualizar estoque, enviar e-mail de confirmação, etc.
console.log('Pedido aprovado:', data.order.id);
}
// Inicia o servidor
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
console.log(`Servidor rodando na porta ${PORT}`);
});Melhores Práticas
-
Responda rapidamente: Seu endpoint deve responder com um código 200 assim que receber o webhook, mesmo que o processamento seja feito de forma assíncrona.
-
Implemente retry: Configure sua aplicação para lidar com retentativas caso ocorra alguma falha no processamento.
-
Valide os tokens: Sempre verifique a autenticidade do webhook através do token incluído no payload.
-
Log de eventos: Mantenha um registro detalhado de todos os webhooks recebidos para fins de auditoria e debugging.
-
Tratamento de erro: Implemente tratamento de erros adequado para evitar que falhas no processamento de um webhook afetem o funcionamento da sua aplicação.
-
Monitoramento: Configure alertas para monitorar falhas na recepção ou processamento dos webhooks.
Suporte
Se você encontrar problemas ao implementar ou utilizar nossos webhooks, entre em contato com nossa equipe de suporte através do e-mail [email protected] ou pelo whatsapp (48) 98870-4837.
