Documentacao de Webhooks

Introducao

Webhooks permitem que seu sistema receba notificacoes automaticas quando eventos importantes acontecem no PitStop. Em vez de consultar nossa API repetidamente, voce configura uma URL que recebera requisicoes HTTP POST sempre que um evento ocorrer.

Recurso Premium

Webhooks estao disponiveis nos planos Profissional e Turbinado.

Como funciona

Voce configura uma URL de endpoint no painel do PitStop
Seleciona quais eventos deseja receber
Opcionalmente, configura um secret para validar a assinatura
Quando um evento ocorre, enviamos um POST para sua URL
Seu servidor processa a requisicao e retorna status 2xx

Autenticacao e Seguranca

Para garantir que as requisicoes sao legitimamente enviadas pelo PitStop, utilizamos assinatura HMAC-SHA256. Quando voce configura um secret, todas as requisicoes incluirao headers de assinatura.

Headers de Seguranca

Header	Descricao
`X-Webhook-Signature`	Assinatura HMAC-SHA256 do payload em hexadecimal
`X-Webhook-Timestamp`	Timestamp Unix em milissegundos do momento do envio
`Content-Type`	Sempre `application/json`

Validando a Assinatura

Para validar que a requisicao e autentica, calcule o HMAC-SHA256 do body da requisicao usando seu secret e compare com o header X-Webhook-Signature.

// Exemplo em Node.js
const crypto = require('crypto');

function validarWebhook(payload, signature, secret) {
    const hmac = crypto.createHmac('sha256', secret);
    const calculado = hmac.update(payload).digest('hex');
    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(calculado)
    );
}

Estrutura do Payload

Todos os webhooks seguem a mesma estrutura base, com dados especificos no campo dados.

{
    "evento": "OS_CRIADA",
    "eventoNome": "Ordem de Servico Criada",
    "timestamp": "2026-01-25T14:30:00",
    "entidadeId": "550e8400-e29b-41d4-a716-446655440000",
    "entidadeTipo": "OrdemServico",
    "dados": {
        // Dados especificos do evento
    }
}

Campo	Tipo	Descricao
`evento`	string	Codigo do evento (ex: OS_CRIADA)
`eventoNome`	string	Nome legivel do evento
`timestamp`	ISO 8601	Data/hora do evento
`entidadeId`	UUID	ID da entidade relacionada
`entidadeTipo`	string	Tipo da entidade (OrdemServico, Cliente, etc)
`dados`	object	Dados especificos do evento

Eventos Disponiveis

O PitStop disponibiliza 16 tipos de eventos que voce pode assinar. Selecione apenas os eventos relevantes para sua integracao.

Ordens de Servico

OS_CRIADA

Disparado quando uma nova ordem de servico e criada.

OS_STATUS_ALTERADO

Disparado quando o status de uma OS muda (ex: ORCAMENTO para APROVADO).

OS_APROVADA

Disparado quando o cliente aprova o orcamento.

OS_FINALIZADA

Disparado quando o servico e finalizado.

OS_ENTREGUE

Disparado quando o veiculo e entregue ao cliente.

OS_CANCELADA

Disparado quando uma OS e cancelada.

Exemplo de payload (OS_CRIADA):

{
    "evento": "OS_CRIADA",
    "eventoNome": "Ordem de Servico Criada",
    "timestamp": "2026-01-25T14:30:00",
    "entidadeId": "550e8400-e29b-41d4-a716-446655440000",
    "entidadeTipo": "OrdemServico",
    "dados": {
        "numero": 1234,
        "status": "ORCAMENTO",
        "valorTotal": 1500.00,
        "cliente": {
            "id": "...",
            "nome": "Joao Silva",
            "telefone": "11999998888"
        },
        "veiculo": {
            "id": "...",
            "placa": "ABC1D23",
            "modelo": "Civic"
        }
    }
}

Clientes

CLIENTE_CRIADO

Disparado quando um novo cliente e cadastrado.

CLIENTE_ATUALIZADO

Disparado quando os dados do cliente sao atualizados.

Veiculos

VEICULO_CRIADO

Disparado quando um novo veiculo e cadastrado.

VEICULO_ATUALIZADO

Disparado quando os dados do veiculo sao atualizados.

Financeiro

PAGAMENTO_RECEBIDO

Disparado quando um pagamento e confirmado.

PAGAMENTO_CANCELADO

Disparado quando um pagamento e cancelado ou estornado.

Exemplo de payload (PAGAMENTO_RECEBIDO):

{
    "evento": "PAGAMENTO_RECEBIDO",
    "timestamp": "2026-01-25T15:00:00",
    "entidadeId": "...",
    "entidadeTipo": "Pagamento",
    "dados": {
        "valor": 1500.00,
        "tipo": "PIX",
        "ordemServicoNumero": 1234,
        "cliente": {
            "nome": "Joao Silva"
        }
    }
}

Estoque

ESTOQUE_BAIXO

Disparado quando uma peca atinge o estoque minimo configurado.

ESTOQUE_MOVIMENTADO

Disparado quando ha entrada ou saida de pecas no estoque.

Exemplo de payload (ESTOQUE_BAIXO):

{
    "evento": "ESTOQUE_BAIXO",
    "timestamp": "2026-01-25T16:00:00",
    "entidadeId": "...",
    "entidadeTipo": "Peca",
    "dados": {
        "sku": "OL-5W30-1L",
        "nome": "Oleo Motor 5W30 1L",
        "quantidadeAtual": 3,
        "quantidadeMinima": 5
    }
}

Manutencao Preventiva

MANUTENCAO_VENCIDA

Disparado quando uma manutencao preventiva vence.

AGENDAMENTO_CRIADO

Disparado quando um agendamento de manutencao e criado.

Exemplos de Codigo

Node.js / Express

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

function validarAssinatura(req) {
    const signature = req.headers['x-webhook-signature'];
    const payload = JSON.stringify(req.body);

    const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET);
    const calculado = hmac.update(payload).digest('hex');

    return crypto.timingSafeEqual(
        Buffer.from(signature || ''),
        Buffer.from(calculado)
    );
}

app.post('/webhook/pitstop', (req, res) => {
    // Validar assinatura
    if (!validarAssinatura(req)) {
        return res.status(401).json({ error: 'Assinatura invalida' });
    }

    const { evento, dados, entidadeId } = req.body;

    console.log(`Evento recebido: ${evento}`);

    switch (evento) {
        case 'OS_CRIADA':
            // Processar nova OS
            console.log(`Nova OS #${dados.numero} criada`);
            break;

        case 'PAGAMENTO_RECEBIDO':
            // Processar pagamento
            console.log(`Pagamento de R$ ${dados.valor} recebido`);
            break;

        case 'ESTOQUE_BAIXO':
            // Enviar alerta
            console.log(`Estoque baixo: ${dados.nome}`);
            break;
    }

    // Sempre retornar 200 para confirmar recebimento
    res.status(200).json({ received: true });
});

app.listen(3000);

Python / Flask

from flask import Flask, request, jsonify
import hmac
import hashlib

app = Flask(__name__)
WEBHOOK_SECRET = 'seu_secret_aqui'

def validar_assinatura(payload, signature):
    calculado = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, calculado)

@app.route('/webhook/pitstop', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Webhook-Signature', '')

    if not validar_assinatura(request.data, signature):
        return jsonify({'error': 'Assinatura invalida'}), 401

    data = request.json
    evento = data.get('evento')
    dados = data.get('dados', {})

    if evento == 'OS_CRIADA':
        print(f"Nova OS #{dados.get('numero')} criada")

    elif evento == 'PAGAMENTO_RECEBIDO':
        print(f"Pagamento de R$ {dados.get('valor')} recebido")

    return jsonify({'received': True}), 200

if __name__ == '__main__':
    app.run(port=3000)

PHP

<?php
$webhookSecret = getenv('WEBHOOK_SECRET');

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$calculado = hash_hmac('sha256', $payload, $webhookSecret);

if (!hash_equals($calculado, $signature)) {
    http_response_code(401);
    echo json_encode(['error' => 'Assinatura invalida']);
    exit;
}

$data = json_decode($payload, true);
$evento = $data['evento'];
$dados = $data['dados'];

switch ($evento) {
    case 'OS_CRIADA':
        error_log("Nova OS #{$dados['numero']} criada");
        break;

    case 'PAGAMENTO_RECEBIDO':
        error_log("Pagamento de R$ {$dados['valor']} recebido");
        break;
}

http_response_code(200);
echo json_encode(['received' => true]);
?>

Politica de Retry

Quando um webhook falha (timeout ou status HTTP diferente de 2xx), o PitStop tentara reenviar automaticamente.

Configuracoes de Retry

Maximo de tentativas: Configuravel (padrao: 3)
Intervalo entre retries: Exponencial (1min, 5min, 15min, 1h)
Timeout: Configuravel (padrao: 30 segundos)
Desativacao automatica: Apos 10 falhas consecutivas

Importante

Seu endpoint deve responder com status 2xx em ate 30 segundos. Para processamentos demorados, retorne 200 imediatamente e processe em background.

Configuracao

Configure seus webhooks diretamente no painel do PitStop em Configuracoes > Webhooks.

Passos para configurar

1 Acesse o painel do PitStop e va em Configuracoes > Webhooks
2 Clique em Novo Webhook
3 Preencha a URL do seu endpoint (deve ser HTTPS em producao)
4 Configure um Secret para validar assinaturas (recomendado)
5 Selecione os eventos que deseja receber
6 Use o botao Testar para verificar a configuracao