Webhooks

Assine eventos de ciclo de vida de plans, routes e stops a partir da API da Routal.

A Routal envia webhooks como HTTP POST para uma URL que você controla quando os recursos mudam de estado. Os 8 eventos disponíveis cobrem o ciclo completo: plan.created / plan.updated / plan.deleted, route.started / route.finished, stop.created / stop.deleted / stop.reported.

Envelope de cada webhook

{
  "created_at": "2026-05-22T08:01:23.456Z",
  "project_id": "4f75d991ac359f8c4c79d762",
  "event_id": "routal.planner.2.stop.reported",
  "meta": { "...": "..." },
  "data": {
    "id": "...",
    "external_id": "ORDER-9001",
    "status": "completed",
    "updated_at": "2026-05-22T08:01:23.000Z"
  }
}

Padrões-chave:

Autenticação por token na URL (/webhooks/routal?token=...) — os webhooks da Routal não têm signature hoje.
Deduplicação por (event_id, data.id, data.updated_at) — não há ID de entrega único no envelope.
Auto-desativação após 50 falhas consecutivas — responda 2xx rápido e processe async.
Retry simples sem cronograma definido — projetado para entregas at-least-once.

A especificação detalhada de cada evento (campos no data, modelos de meta por contexto, exemplos de handler em TS/Python/Express/Flask) vive em inglês.

Ler a referência completa de Webhooks em inglês →

Envelope de cada webhook

On this page