Receive webhooks

Drometra notifies your system with an HTTPS POST when something happens in your company, such as a new order or a completed delivery. Notifications follow the Standard Webhooks format and are signed.

Prepara el destino

You need an HTTPS address on port 443 with a public name, without a direct IP, credentials in the URL or redirects. Drometra doesn't publish fixed outbound IPs, so security lies in verifying the signature. Destinations are created by an administrator with two-step verification.

Crea el destino y guarda el secreto

Choose which events you want to receive. The response includes the signing secret (whsec_…) only once: store it in your secrets manager.

POST /v1/webhooks/endpoints

curl -X POST "https://api.drometra.com/v1/webhooks/endpoints" \
  -H "Authorization: Bearer $DROMETRA_TOKEN" \
  -H "x-tenant-id: $DROMETRA_TENANT" \
  -H "idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://empresa.cl/webhooks/drometra",
    "description": "ERP: entregas",
    "eventTypes": ["field.stop.delivered", "field.stop.failed"]
  }'

Event	When it arrives	In data
distribution.order.created	An order was created.	orderId, reference, state
distribution.order.cancelled	An order was cancelled.	orderId, reference, state
routing.plan.approved	A route plan was approved.	routePlanId, previewId, routeCount, unassignedCount
field.route.assigned	A route was assigned to a vehicle.	routeId, routePlanId, vehicleRouteId, serviceDate, fleetVehicleId, stopCount, orderIds
field.route.cancelled	A route was cancelled.	routeId, serviceDate
field.route.started	The driver started the route.	routeId
field.stop.delivered	A stop was delivered.	routeId, stopId, orderId, reference, outcomeAt, evidenceCount
field.stop.failed	A delivery couldn't be made.	routeId, stopId, orderId, reference, outcomeAt, evidenceCount
field.route.finished	The route finished.	routeId, finishedAt, summary

Verifica la firma de cada aviso

Each notification carries webhook-id, webhook-timestamp and webhook-signature. The signature is an HMAC SHA-256 of id.timestamp.body, calculated over the body exactly as it arrived, before parsing the JSON.

verify

import { createHmac, timingSafeEqual } from "node:crypto";

export function verificar(secreto, headers, cuerpoCrudo) {
  const id = headers["webhook-id"], ts = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // ±5 minutos
  const clave = Buffer.from(secreto.replace(/^whsec_/, ""), "base64");
  const esperada = createHmac("sha256", clave).update(`${id}.${ts}.${cuerpoCrudo}`).digest();
  return headers["webhook-signature"].split(" ").some((parte) => {
    const dada = Buffer.from(parte.replace(/^v1,/, ""), "base64");
    return dada.length === esperada.length && timingSafeEqual(dada, esperada);
  });
}

The body carries identifiers, references, states, counts and dates, never personal data. If you need more, query it in the API.

body

{
  "id": "5f0c1e2a-…",
  "type": "field.stop.delivered",
  "timestamp": "2026-10-21T14:03:11.000Z",
  "tenantId": "7a1d0c44-…",
  "version": 1,
  "data": {
    "routeId": "…", "stopId": "…", "orderId": "…",
    "reference": "1043", "outcomeAt": "2026-10-21T14:02:58.000Z", "evidenceCount": 2
  }
}

Responde rápido y procesa una sola vez

Respond 2xx in under 10 seconds and do the work afterwards. Otherwise Drometra retries after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours: eight attempts over about 28 hours. Delivery is at least once and without guaranteed order, so store the webhook-id you've processed and discard repeats.

After 20 failed deliveries in a row the destination disables itself; reactivate it when your receiver is healthy.

Prueba, revisa y rota

Send a test event (webhook.test) with POST /v1/webhooks/endpoints/{id}/test. Each delivery stays in the log for 30 days (GET /v1/webhooks/deliveries), with each attempt and its result, and can be retried by hand. The secret is rotated with POST /v1/webhooks/endpoints/{id}/secrets: during the grace period, of up to 7 days, each notification carries two signatures and either one is valid.

See the webhook routes