NetGuincho
NetGuincho

Docs

Webhooks

Integração Corporativa

Webhooks

A NetGuincho pode notificar seu sistema em tempo real sobre eventos do ciclo de vida de cada chamado. Recomendado para evitar polling e manter seus dashboards atualizados.

1. Configuração

Configure a URL de webhook e o segredo de assinatura no painel administrativo ou via API:

cURL
curl -X PATCH 'https://api.netguincho.com.br/api/v1/insurer-portal/webhook' \
  -H 'X-API-Key: live_sk_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://api.suaempresa.com/webhooks/netguincho",
    "secret": "whsec_<gerado-pelo-painel>"
  }'

2. Eventos disponíveis

EventoQuando dispara
service.requestedChamado criado com sucesso após validação de elegibilidade.
service.dispatchedPrestador aceitou o chamado. Inclui ETA e dados do guincheiro.
service.completedAtendimento concluído. Inclui duração e custo final.
service.cancelledChamado cancelado. Indica se contou no limite mensal (counted).
usage.limit_reachedSegurado atingiu o limite mensal de acionamentos.

3. Formato do payload

Todos os eventos seguem o envelope abaixo:

JSON
{
  "event_id": "evt_2K3lF8mZpqR9aB7cX1yY",
  "event_type": "service.dispatched",
  "created_at": "2026-04-18T14:35:22.000Z",
  "insurer_id": "9b3f...",
  "data": {
    "request_id": "f0a2b3c4-...",
    "insurer_customer_id": "2a1c...",
    "provider_id": "p_4e5f...",
    "provider_name": "Guincho Express SP",
    "eta_minutes": 18,
    "tracking_url": "https://app.netguincho.com.br/chamado/f0a2..."
  }
}

Headers enviados

HTTP
POST /webhooks/netguincho HTTP/1.1
Host: api.suaempresa.com
Content-Type: application/json
User-Agent: NetGuincho-Webhook/1.0
X-NetGuincho-Event: service.dispatched
X-NetGuincho-Event-Id: evt_2K3lF8mZpqR9aB7cX1yY
X-NetGuincho-Signature: sha256=a3b1c2d4e5f6...
X-NetGuincho-Timestamp: 1729269322

4. Verificação de assinatura (HMAC)

Cada requisição é assinada com HMAC SHA-256 usando o segredo configurado. Verifique a assinatura para garantir que a requisição realmente veio da NetGuincho.

TypeScript
import crypto from 'node:crypto';
import express from 'express';

const app = express();

// IMPORTANTE: precisa do raw body para validar a assinatura
app.post(
  '/webhooks/netguincho',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.header('X-NetGuincho-Signature') ?? '';
    const timestamp = req.header('X-NetGuincho-Timestamp') ?? '';
    const secret = process.env.NETGUINCHO_WEBHOOK_SECRET!;

    const payload = `${timestamp}.${req.body.toString('utf8')}`;
    const expected =
      'sha256=' + crypto.createHmac('sha256', secret).update(payload).digest('hex');

    const ok =
      signature.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

    if (!ok) return res.status(401).send('invalid signature');

    const event = JSON.parse(req.body.toString('utf8'));
    // ... processe o evento ...
    res.status(200).send('ok');
  },
);

5. Retry policy

Se o seu endpoint não responder com 2xx em até 5 segundos, a NetGuincho tenta novamente:

  • 1ª tentativa: imediata
  • 2ª tentativa: após 1 minuto
  • 3ª tentativa: após 5 minutos
  • 4ª tentativa: após 30 minutos

Após 4 tentativas falhas, o evento é marcado como failed e o time de operações da NetGuincho é notificado. Você pode reenviar manualmente os eventos falhos pelo painel administrativo.

6. Boas práticas

  • Idempotência: use event_id como chave única para evitar processar o mesmo evento duas vezes em caso de retry.
  • Resposta rápida: responda 2xx imediatamente e processe o evento em background (fila).
  • Tolerância a campos novos: não falhe se receber campos adicionais — eles podem ser adicionados em versões futuras sem aviso.
  • Logs: mantenha logs de eventos recebidos por pelo menos 30 dias para suporte e auditoria.