Integrar con Webhooks

Configura un endpoint para recibir eventos de Falconext.

Los webhooks te avisan cuando algo cambia, sin que tengas que preguntar. Esta guía crea un endpoint receptor y lo registra en Falconext.

Expón un endpoint HTTPS

Crea una ruta pública que reciba POST con cuerpo JSON. En desarrollo puedes usar un túnel (ngrok, Cloudflare Tunnel) para exponer tu localhost.

Regístralo en Falconext

Indica la URL y los eventos que te interesan.

Terminal

curl https://api.falconext.pe/api/v1/logistics/webhook_endpoints \
  -H "Authorization: Bearer $FALCONEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tu-app.com/webhooks/falconext",
        "events": ["order.delivered", "order.failed"] }'

Guarda el secret que devuelve: lo usarás para verificar la firma.

Verifica la firma y responde 2xx

Valida la cabecera Falconext-Signature antes de procesar. Responde en menos de 5 s.

JavaScript

app.post("/webhooks/falconext",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sig = req.header("Falconext-Signature");
    if (!verifySignature(req.body, sig, process.env.WEBHOOK_SECRET)) {
      return res.status(400).send("firma inválida");
    }
    // encola el evento y responde rápido
    res.sendStatus(200);
  });

Responde rápido, procesa después

No hagas trabajo pesado dentro del handler. Encola el evento y responde 2xx de inmediato, o arriesgas timeouts y reintentos.

Consumir eventos

Cómo reaccionar a cada tipo de evento.