Webhooks

Os Webhooks enviam notificações de eventos para o seu endpoint HTTP quando algo muda no TrucklineMP. Configure-os no Console do Desenvolvedor.

Os Webhooks complementam a Public API. Use a API para consultar ou obter dados sob demanda. Use Webhooks quando o seu serviço deve reagir imediatamente a alterações na plataforma.

Criar um webhook

Abra Webhooks no Console do Desenvolvedor.
Clique em Create Webhook.
Informe um nome, o URL do endpoint HTTPS, e selecione os eventos que quer.
Copie o segredo de assinatura quando for mostrado. Você precisa dele para verificar as entregas.

Cada webhook pertence à sua conta de desenvolvedor. Pode criar múltiplos endpoints para diferentes ambientes (staging, produção).

Formato de entrega

O TrucklineMP envia um POST HTTP com um corpo JSON:

{
  "event": "vtc.member_joined",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-06-30T12:00:00.000Z",
  "data": {
    "vtcId": 42,
    "userId": "user_abc",
    "role": "Driver"
  }
}

Cabeçalhos do pedido

Cabeçalho	Descrição
`Content-Type`	`application/json`
`X-TrucklineMP-Signature`	Assinatura HMAC-SHA256 (`sha256=<hex>`)
`X-TrucklineMP-Event`	Tipo de evento (por exemplo `vtc.member_joined`)
`X-TrucklineMP-Delivery`	ID de entrega único (corresponde a `event_id`)

Também pode anexar cabeçalhos personalizados nas configurações do webhook. Nomes de cabeçalhos sensíveis (Authorization, Cookie, e semelhantes) são removidos dos registros de entrega.

Verificar assinaturas

Calcula a assinatura esperada sobre o corpo bruto do pedido (raw body) usando o seu segredo de webhook:

expected = "sha256=" + HMAC_SHA256(secret, raw_body)

Compara expected com o cabeçalho X-TrucklineMP-Signature usando uma comparação de tempo constante. Rejeita requisições com assinaturas inválidas antes de processar a carga útil (payload).

Exemplo (Node.js):

import { createHmac, timingSafeEqual } from "crypto";

function verifySignature(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  if (!signatureHeader || signatureHeader.length !== expected.length) return false;
  return timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

Tentativas de reenvio

As entregas falhadas são reenviadas automaticamente. Atrasos de reenvio padrões:

Tentativa	Atraso após falha
1	30 segundos
2	2 minutos
3	10 minutos

Uma entrega é bem-sucedida quando o seu endpoint devolve HTTP 2xx. Redirecionamentos (3xx) são tratados como falhas. Os timeouts têm padrão de 30 segundos por tentativa.

O histórico e o estado de entrega são visíveis no console. Use Send Test para acionar um evento webhook.test contra o seu endpoint.

Catálogo de eventos

Assine apenas os eventos de que sua integração precisa.

Usuários

Evento	Descrição
`user.updated`	O perfil de um usuário foi atualizado
`user.banned`	Um usuário foi banido
`user.unbanned`	O banimento de um usuário foi removido

VTCs

Evento	Descrição
`vtc.created`	Foi criada uma nova VTC
`vtc.member_joined`	Um usuário aderiu a uma VTC
`vtc.member_left`	Um usuário saiu de uma VTC
`vtc.updated`	Os detalhes da VTC foram atualizados

Eventos

Evento	Descrição
`event.created`	Foi publicado um novo evento
`event.updated`	Um evento foi atualizado
`event.cancelled`	Um evento foi cancelado
`event.rsvp`	Um usuário confirmou presença (RSVP) num evento

Moderação

Evento	Descrição
`ban.issued`	Foi emitido um banimento
`ban.appealed`	Foi apresentado um recurso de banimento
`ban.appeal_resolved`	Um recurso de banimento foi resolvido

API (a nível de conta)

Evento	Descrição
`api.rate_limit_hit`	Um dos seus tokens de API atingiu o limite de taxa
`api.token_revoked`	Um token de API foi revogado

Teste

Evento	Descrição
`webhook.test`	Entrega de teste manual a partir do console

Os campos exatos da carga útil variam conforme o evento. Trata data como o objeto específico do evento e ignora campos desconhecidos para garantir compatibilidade futura.

Requisitos do endpoint

Use HTTPS em produção.
Responda com 2xx rapidamente. Delega trabalho pesado a uma fila em segundo plano.
Só devolvas 2xx depois de ter aceitado a carga útil. O TrucklineMP não reenviará entregas bem-sucedidas.
Não sigas redirecionamentos do lado do recetor. Respostas de redirecionamento fazem a entrega falhar.

URLs de rede privada e destinos inseguros são bloqueados pela plataforma.

Webhooks de anúncio de VTC (funcionalidade separada)

Os proprietários de VTC podem configurar webhooks de anúncio do Discord a partir do painel de gestão da sua VTC. Esses webhooks publicam embeds formatados no Discord quando ocorrem eventos da VTC (adesões de membros, candidaturas, e semelhantes).

Os webhooks do Console do Desenvolvedor são diferentes. São endpoints HTTP a nível de conta para o seu código de integração. Ver Anúncios de VTC para a funcionalidade focada no Discord.