MapogosAPI Docs
/
Eventos

Webhooks

O Mapogos envia um POST para a URL do seu sistema quando um evento acontece — sem você precisar consultar a API o tempo todo.

Configurando

  1. Publique no seu sistema um endereço https público que aceite POST com JSON.
  2. No painel: API do Sistema → Webhooks → Novo webhook. Escolha a chave, informe a URL e marque os eventos (só aparecem os de módulos que a chave pode ler).
  3. Copie o segredo do webhook (exibido uma vez) e guarde em MAPOGOS_WEBHOOK_SECRET.
  4. Use o botão Testar para receber o evento teste.ping.

Eventos disponíveis

EventoQuando aconteceExige leitura em
locacao.criadaNovo contrato de locação ou venda criado.Locações
locacao.encerradaContrato encerrado/finalizado.Locações
pagamento.criadoNova cobrança gerada.Pagamentos
pagamento.confirmadoCobrança baixada como paga (PIX, manual ou banco).Pagamentos
pagamento.vencidoCobrança pendente passou do vencimento (disparado no dia seguinte ao vencimento).Pagamentos
pagamento.canceladoCobrança cancelada.Pagamentos
veiculo.criadoVeículo cadastrado.Veículos
veiculo.bloqueadoRastreador passou para bloqueado.Veículos
veiculo.desbloqueadoRastreador passou para desbloqueado.Veículos
cliente.criadoCliente cadastrado.Clientes
cliente.atualizadoCadastro do cliente alterado.Clientes
os.criadaOrdem de serviço aberta.Ordens de Serviço
os.concluidaOrdem de serviço concluída.Ordens de Serviço
vistoria.concluidaVistoria validada.Vistorias
acordo.criadoAcordo/parcelamento criado.Acordos
acordo.quitadoAcordo quitado.Acordos
acordo.parcela_pagaParcela de acordo paga.Acordos
multa.criadaMulta registrada para um veículo.Multas

Formato do aviso

CabeçalhoConteúdo
X-Mapogos-EventoNome do evento
X-Mapogos-Evento-IdId único do evento (use para não processar duas vezes)
X-Mapogos-EntregaNúmero da entrega
X-Mapogos-TimestampMomento do envio (epoch)
X-Mapogos-Assinaturasha256= + HMAC-SHA256 de timestamp.corpo

O campo dados traz o registro no mesmo formato da API, respeitando as carteiras e a permissão LGPD da chave.

Corpo do POST enviado ao seu sistema200 OK
{
    "id": "evt_88231_1a2b3c",
    "evento": "pagamento.confirmado",
    "modulo": "pagamentos",
    "criado_em": "2026-10-08T14:30:00-03:00",
    "ambiente": "live",
    "dados": {
        "id": 1024,
        "rental_id": 512,
        "amount": "150.00",
        "original_amount": "150.00",
        "status": "pago",
        "method": "pix",
        "due_date": "2026-10-15",
        "paid_at": "2026-10-08T14:30:00-03:00",
        "note": "Aluguel semanal"
    }
}

Validando a assinatura

  1. Leia o corpo bruto da requisição (antes de converter o JSON).
  2. Calcule HMAC-SHA256(segredo, timestamp + "." + corpo).
  3. Compare com X-Mapogos-Assinatura usando comparação de tempo constante.
  4. Rejeite timestamps com mais de 5 minutos de diferença.
Receptor com validação
<?php
// webhook.php — recebe avisos do Mapogos
$segredo = getenv('MAPOGOS_WEBHOOK_SECRET');
$corpo   = file_get_contents('php://input');
$ts      = $_SERVER['HTTP_X_MAPOGOS_TIMESTAMP'] ?? '';
$assin   = $_SERVER['HTTP_X_MAPOGOS_ASSINATURA'] ?? '';

$esperado = 'sha256=' . hash_hmac('sha256', $ts . '.' . $corpo, $segredo);
if (!hash_equals($esperado, $assin) || abs(time() - (int)$ts) > 300) {
  http_response_code(401);
  exit;
}

$evento = json_decode($corpo, true);
if (!jaProcessado($evento['id'])) {          // evita processar duas vezes
  enfileirar($evento);                        // processe depois, responda rápido
}
http_response_code(200);

Entregas e novas tentativas

TentativaQuando
1ªEm até 1 minuto após o evento
2ª1 min depois da falha
3ª5 min depois
4ª30 min depois
5ª2 h depois
6ª (última)12 h depois

Considera-se entregue quando seu sistema responde 2xx em até 10 segundos. Depois da última tentativa a entrega fica como falha e pode ser reenviada pelo painel (histórico de entregas). A entrega é "pelo menos uma vez": use o id do evento para ignorar repetições.