Webhooks

Recibe eventos del ciclo de vida de cada pedido en tiempo real, con firma HMAC y reintentos.

Cada pedido emite eventos a medida que avanza por su ciclo de vida. Registra un endpoint HTTPS y Falconext te notificará al instante en cada cambio de estado.

Cómo funciona

Registra un endpoint con POST /webhook_endpoints, suscríbete a los eventos que te interesen y responde con 2xx en menos de 5 segundos. Si tu servidor falla, reintentamos con backoff exponencial hasta 24 horas.

Verifica la firma

Cada request incluye la cabecera Falconext-Signature. Calcula el HMAC del cuerpo con el secret de tu endpoint y compáralo en tiempo constante.

HTTP

POST /webhooks/falconext HTTP/1.1
Content-Type: application/json
Falconext-Event: order.delivered
Falconext-Order-Id: ord_3xK8p2Qm
Falconext-Signature: t=1719849600,v1=8b7c…e2
Falconext-Attempt: 1

JavaScript

import crypto from "node:crypto";

export function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload, "utf8")
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature),
  );
}

Valida siempre la firma

No proceses un evento sin verificar su firma. Descarta cualquier request cuya firma no coincida.

Catálogo de eventos

order.created

Creado
Asignado
Recogido
En tránsito
Entregado

Eventos del ciclo de vida de un pedido.7 eventos

order.createdciclo

El pedido se registró en Falconext y está pendiente de validación y asignación.

Etapa 1 del ciclo de vida · avanza el estado de la entrega.

order.created · payload

JSON

{
  "event": "order.created",
  "data": {
    "id": "ord_3xK8p2Qm",
    "object": "order",
    "external_order_id": "ORD-10482",
    "tracking_code": "FX-7Q2M8K",
    "status": "pending",
    "created_at": "2025-07-01T14:03:11Z"
  }
}

order.assignedciclo

El pedido se asignó a un despacho/ruta y a un repartidor.

Etapa 2 del ciclo de vida · avanza el estado de la entrega.

order.assigned · payload

JSON

{
  "event": "order.assigned",
  "data": {
    "id": "ord_3xK8p2Qm",
    "object": "order",
    "external_order_id": "ORD-10482",
    "tracking_code": "FX-7Q2M8K",
    "status": "assigned",
    "courier": {
      "id": "crr_91",
      "name": "Repartidor"
    }
  }
}

order.picked_upciclo

El repartidor recogió el paquete en el almacén de origen.

Etapa 3 del ciclo de vida · avanza el estado de la entrega.

order.picked_up · payload

JSON

{
  "event": "order.picked_up",
  "data": {
    "id": "ord_3xK8p2Qm",
    "object": "order",
    "external_order_id": "ORD-10482",
    "tracking_code": "FX-7Q2M8K",
    "status": "picked_up",
    "picked_up_at": "2025-07-01T14:35:00Z"
  }
}

order.in_transitciclo

El pedido va en camino hacia la dirección de entrega.

Etapa 4 del ciclo de vida · avanza el estado de la entrega.

order.in_transit · payload

JSON

{
  "event": "order.in_transit",
  "data": {
    "id": "ord_3xK8p2Qm",
    "object": "order",
    "external_order_id": "ORD-10482",
    "tracking_code": "FX-7Q2M8K",
    "status": "in_transit",
    "eta_minutes": 18
  }
}

order.deliveredfinal

El pedido se entregó con éxito y cuenta con prueba de entrega (firma/foto).

Etapa 5 del ciclo de vida · avanza el estado de la entrega.

order.delivered · payload

JSON

{
  "event": "order.delivered",
  "data": {
    "id": "ord_3xK8p2Qm",
    "object": "order",
    "external_order_id": "ORD-10482",
    "tracking_code": "FX-7Q2M8K",
    "status": "delivered",
    "proof": {
      "receiver_name": "María Fernández",
      "signature_url": "https://cdn.falconext.com/pod/sig_9Q2m.png"
    },
    "delivered_at": "2025-07-01T15:12:44Z"
  }
}

order.failedexcepción

La entrega no pudo completarse (cliente ausente, dirección errónea, rechazo…).

order.failed · payload

JSON

{
  "event": "order.failed",
  "data": {
    "id": "ord_3xK8p2Qm",
    "object": "order",
    "external_order_id": "ORD-10482",
    "tracking_code": "FX-7Q2M8K",
    "status": "failed",
    "reason": "customer_absent"
  }
}

order.returnedexcepción

El paquete regresó al origen tras uno o más intentos fallidos.

order.returned · payload

JSON

{
  "event": "order.returned",
  "data": {
    "id": "ord_3xK8p2Qm",
    "object": "order",
    "external_order_id": "ORD-10482",
    "tracking_code": "FX-7Q2M8K",
    "status": "returned",
    "returned_at": "2025-07-01T18:22:40Z"
  }
}