--- title: "POST /api/v3/webhooks" method: POST path: "/api/v3/webhooks" tags: ["webhooks"] --- # POST /api/v3/webhooks `POST /api/v3/webhooks` ## Request - Base URL: `https://delivery.99minutos.com` - URL: `https://delivery.99minutos.com/api/v3/webhooks` - Auth: HTTP bearer Submit a new webhook configuration. You can set 2 settings at most. ### Eventos notificados por defecto Al registrar un webhook, se notifican por defecto los eventos correspondientes a los siguientes 15 estados: | StatusCode | StatusName | | --- | --- | | `2002` | `onRoadToPickup` | | `2003` | `collected` | | `2101` | `unsuccessfulPickup` | | `3001` | `stored` | | `3004` | `onLinehaul` | | `4001` | `onRoadToDelivery` | | `4002` | `delivered` | | `4101` | `unsuccessfulDelivery` | | `5001` | `onRoadToReturn` | | `5002` | `returned` | | `5101` | `unsuccessfulReturn` | | `8001` | `stolen` | | `8002` | `lost` | | `8003` | `cancelled` | | `8005` | `invalidAddress` | `StatusCode` se envía como string y `StatusName` en camelCase. **Nota:** El array de `Events` siempre envía todo el histórico de eventos del envío registrados hasta el momento. En flujos terminales completos (`delivered`, `returned`) se visualizan todos los estados del recorrido, mientras que en cancelaciones e incidencias se presentan los eventos acontecidos hasta el reporte. 1. Happy path con evento terminal 4002 (delivered): ```json { "StatusName": "delivered", // Current status of the order, sent in camelCase. "TrackingId": "2139671481", // Identifier generated by 99minutos "InternalKey": "SOME_ID", // Identifier sent by the customer "Destination": { "zone": "MCH4" }, "Driver": { "id": "6a0c99c0734104a5696a3381" }, "Route": "MX0-MCH2-3381-5", "Events": [ // List of events through which the shipment has transited in ascending order { "StatusCode": "1002", "StatusName": "confirmed", "CreatedAt": "2023-01-02 23:55:39", // UTC Time "Data": { "comment": "NEW_ORDER_CONFIRMED", // Additional event information "evidence": [] // Evidence of transition } }, { "StatusCode": "2003", "StatusName": "collected", "CreatedAt": "2023-01-03 20:12:43", "Data": { "comment": "Recolectada por el veloz Don Veloz N/A 99m B 2eeb2a6", "evidence": [] } }, { "StatusCode": "10000", "StatusName": "inUpdates", "Category": "ETA", "CreatedAt": "2023-01-03 20:15:00", "Data": { "comment": "ETA updated", "evidence": [], "eta": "2023-01-05 18:30:00" } }, { "StatusCode": "3001", "StatusName": "stored", "CreatedAt": "2023-01-03 22:20:02", "Data": { "comment": "En estación MX5 por módulo de inducción", "evidence": [] } }, { "StatusCode": "3004", "StatusName": "onLinehaul", "CreatedAt": "2023-01-04 01:13:46", "Data": { "comment": "En camino a estación Tultitlán desde estación Pantaco por jhon.doe el número de orden 2139671481", "evidence": [] } }, { "StatusCode": "3001", "StatusName": "stored", "CreatedAt": "2023-01-04 04:17:42", "Data": { "comment": "En estación MX0 por módulo de inducción", "evidence": [] } }, { "StatusCode": "3002", "StatusName": "onContainer", "CreatedAt": "2023-01-04 06:28:12", "Data": { "comment": "Contenerizado en la estación MX0 en el contenedor VQA-319 en el finger F1", "evidence": [] } }, { "StatusCode": "3003", "StatusName": "chargedToVehicle", "CreatedAt": "2023-01-05 05:13:24", "Data": { "comment": "Subida al line haul del veloz Jhon Doe con las placas LA37321 en la estacion MX0 dentro del contenedor VQA-319", "evidence": [] } }, { "StatusCode": "3004", "StatusName": "onLinehaul", "CreatedAt": "2023-01-05 06:31:29", "Data": { "comment": "Despachado de la estación MX0 hacia la estación MCH2, en el line haul del veloz Jhon Doe con las placas LA37321 en el contenedor VQA-319", "evidence": [] } }, { "StatusCode": "3001", "StatusName": "stored", "CreatedAt": "2023-01-05 16:37:06", "Data": { "comment": "En estación final MCH2 por módulo de inducción", "evidence": [] } }, { "StatusCode": "4001", "StatusName": "onRoadToDelivery", "CreatedAt": "2023-01-05 16:01:40", "Data": { "comment": "Asignada a entrega en la estación al veloz Jhon. Ruta: 49b91331-2be0-2fd4-9b25-1accc772f937", "evidence": [] } }, { "StatusCode": "4002", "StatusName": "delivered", "CreatedAt": "2023-01-05 16:45:54", "Data": { "comment": "Titular - Carlos Ramirez | CP", "evidence": [ "[https://copilot-image-proxy-qndxoltwga-uc.a.run.app/view/62b6fec1836a6321a5ca5a4a.jpeg](https://copilot-image-proxy-qndxoltwga-uc.a.run.app/view/62b6fec1836a6321a5ca5a4a.jpeg)", "[https://copilot-image-proxy-qndxoltwga-uc.a.run.app/view/63b1fec1b030b63f06db10a5.jpeg](https://copilot-image-proxy-qndxoltwga-uc.a.run.app/view/63b1fec1b030b63f06db10a5.jpeg)", "[https://copilot-image-proxy-qndxoltwga-uc.a.run.app/view/62b1fab2b031b63d01da31b7.jpeg](https://copilot-image-proxy-qndxoltwga-uc.a.run.app/view/62b1fab2b031b63d01da31b7.jpeg)" ], "destination": { "zone": "MCH4" }, "driver": { "id": "6a0c99c0734104a5696a3381" }, "route": "MX0-MCH2-3381-5" } } ] } ``` 2. Ciclo con evento terminal 5002 (returned): ```json { "StatusName": "returned", "TrackingId": "2139671481", "InternalKey": "SOME_ID", "Destination": { "zone": "MCH4" }, "Driver": { "id": "6a0c99c0734104a5696a3381" }, "Route": "MX0-MCH2-3381-5", "Events": [ { "StatusCode": "1002", "StatusName": "confirmed", "CreatedAt": "2023-01-02 23:55:39", "Data": { "comment": "NEW_ORDER_CONFIRMED", "evidence": [] } }, { "StatusCode": "2003", "StatusName": "collected", "CreatedAt": "2023-01-03 20:12:43", "Data": { "comment": "Recolectada por el veloz Don Veloz N/A 99m B 2eeb2a6", "evidence": [] } }, { "StatusCode": "10000", "StatusName": "inUpdates", "Category": "ETA", "CreatedAt": "2023-01-03 20:15:00", "Data": { "comment": "ETA updated", "evidence": [], "eta": "2023-01-05 18:30:00" } }, { "StatusCode": "3001", "StatusName": "stored", "CreatedAt": "2023-01-03 22:20:02", "Data": { "comment": "En estación MX5 por módulo de inducción", "evidence": [] } }, { "StatusCode": "3004", "StatusName": "onLinehaul", "CreatedAt": "2023-01-04 01:13:46", "Data": { "comment": "En camino a estación Tultitlán desde estación Pantaco por jhon.doe el número de orden 2139671481", "evidence": [] } }, { "StatusCode": "3001", "StatusName": "stored", "CreatedAt": "2023-01-04 04:17:42", "Data": { "comment": "En estación MX0 por módulo de inducción", "evidence": [] } }, { "StatusCode": "3002", "StatusName": "onContainer", "CreatedAt": "2023-01-04 06:28:12", "Data": { "comment": "Contenerizado en la estación MX0 en el contenedor VQA-319 en el finger F1", "evidence": [] } }, { "StatusCode": "3003", "StatusName": "chargedToVehicle", "CreatedAt": "2023-01-05 05:13:24", "Data": { "comment": "Subida al line haul del veloz Jhon Doe con las placas LA37321 en la estacion MX0 dentro del contenedor VQA-319", "evidence": [] } }, { "StatusCode": "3004", "StatusName": "onLinehaul", "CreatedAt": "2023-01-05 06:31:29", "Data": { "comment": "Despachado de la estación MX0 hacia la estación MCH2, en el line haul del veloz Jhon Doe con las placas LA37321 en el contenedor VQA-319", "evidence": [] } }, { "StatusCode": "3001", "StatusName": "stored", "CreatedAt": "2023-01-05 16:37:06", "Data": { "comment": "En estación final MCH2 por módulo de inducción", "evidence": [] } }, { "StatusCode": "4001", "StatusName": "onRoadToDelivery", "CreatedAt": "2023-01-05 16:01:40", "Data": { "comment": "Asignada a entrega en la estación al veloz Jhon. Ruta: 49b91331-2be0-2fd4-9b25-1accc772f937", "evidence": [] } }, { "StatusCode": "5002", "StatusName": "returned", "CreatedAt": "2023-01-05 17:10:20", "Data": { "comment": "Devolución confirmada en estación", "evidence": [ "[https://copilot-image-proxy-qndxoltwga-uc.a.run.app/view/62b6fec1836a6321a5ca5a4a.jpeg](https://copilot-image-proxy-qndxoltwga-uc.a.run.app/view/62b6fec1836a6321a5ca5a4a.jpeg)" ], "destination": { "zone": "MCH4" }, "driver": { "id": "6a0c99c0734104a5696a3381" }, "route": "MX0-MCH2-3381-5" } } ] } ``` 3. invalidAddress (8005): ```json { "StatusName": "invalidAddress", "TrackingId": "2139671481", "InternalKey": "SOME_ID", "Events": [ { "StatusCode": "8005", "StatusName": "invalidAddress", "CreatedAt": "2023-01-05 16:30:00", "Category": "TRANSITION", "Data": { "comment": "Dirección no localizada por falta de numeración o referencias", "evidence": [] } } ] } ``` 4. cancelled (8003): ```json { "StatusName": "cancelled", "TrackingId": "2139671481", "InternalKey": "SOME_ID", "Events": [ { "StatusCode": "8003", "StatusName": "cancelled", "CreatedAt": "2023-01-03 11:20:15", "Category": "TRANSITION", "Data": { "comment": "Cancelación solicitada por el cliente", "evidence": [] } } ] } ``` 5. stolen (8001): ```json { "StatusName": "stolen", "TrackingId": "2139671481", "InternalKey": "SOME_ID", "Events": [ { "StatusCode": "8001", "StatusName": "stolen", "CreatedAt": "2023-01-05 14:10:00", "Category": "TRANSITION", "Data": { "comment": "Incidencia reportada en ruta: robo de unidad", "evidence": [] } } ] } ``` 6. lost (8002): ```json { "StatusName": "lost", "TrackingId": "2139671481", "InternalKey": "SOME_ID", "Events": [ { "StatusCode": "8002", "StatusName": "lost", "CreatedAt": "2023-01-05 18:00:00", "Category": "TRANSITION", "Data": { "comment": "Paquete declarado como extraviado tras proceso de investigación", "evidence": [] } } ] } ``` Los siguientes ejemplos de entrega fallida y retorno fallido son ficticios y corresponden al mismo envío. Las fechas están en UTC y las URLs de evidencia son ilustrativas. Para estos estados, el payload no incluye `Destination`, `Driver` ni `Route`; esos campos se generan para `delivered` y `returned` cuando la funcionalidad está habilitada y existen datos disponibles. 7. Entrega fallida (4101, unsuccessfulDelivery): ```json { "StatusName": "unsuccessfulDelivery", "TrackingId": "9900000001", "InternalKey": "ORDER-EXAMPLE-001", "DeliveryType": "NXD", "Location": null, "Category": "", "Events": [ { "StatusCode": "1002", "StatusName": "confirmed", "Category": "", "CreatedAt": "2023-01-02 23:55:00", "Data": { "comment": "NEW_ORDER_CONFIRMED", "evidence": [] } }, { "StatusCode": "2003", "StatusName": "collected", "Category": "", "CreatedAt": "2023-01-03 20:12:00", "Data": { "comment": "Paquete recolectado", "evidence": [] } }, { "StatusCode": "3001", "StatusName": "stored", "Category": "", "CreatedAt": "2023-01-05 15:30:00", "Data": { "comment": "En estación final MCH2", "evidence": [] } }, { "StatusCode": "4001", "StatusName": "onRoadToDelivery", "Category": "", "CreatedAt": "2023-01-05 16:00:00", "Data": { "comment": "Paquete asignado a ruta de entrega", "evidence": [] } }, { "StatusCode": "4101", "StatusName": "unsuccessfulDelivery", "Category": "", "CreatedAt": "2023-01-05 18:45:00", "Data": { "comment": "Intento de entrega no exitoso: destinatario ausente", "evidence": [ "https://example.com/evidence/unsuccessful-delivery.jpg" ] } } ] } ``` 8. Retorno fallido (5101, unsuccessfulReturn): ```json { "StatusName": "unsuccessfulReturn", "TrackingId": "9900000001", "InternalKey": "ORDER-EXAMPLE-001", "DeliveryType": "NXD", "Location": null, "Category": "", "Events": [ { "StatusCode": "1002", "StatusName": "confirmed", "Category": "", "CreatedAt": "2023-01-02 23:55:00", "Data": { "comment": "NEW_ORDER_CONFIRMED", "evidence": [] } }, { "StatusCode": "2003", "StatusName": "collected", "Category": "", "CreatedAt": "2023-01-03 20:12:00", "Data": { "comment": "Paquete recolectado", "evidence": [] } }, { "StatusCode": "3001", "StatusName": "stored", "Category": "", "CreatedAt": "2023-01-05 15:30:00", "Data": { "comment": "En estación final MCH2", "evidence": [] } }, { "StatusCode": "4001", "StatusName": "onRoadToDelivery", "Category": "", "CreatedAt": "2023-01-05 16:00:00", "Data": { "comment": "Paquete asignado a ruta de entrega", "evidence": [] } }, { "StatusCode": "4101", "StatusName": "unsuccessfulDelivery", "Category": "", "CreatedAt": "2023-01-05 18:45:00", "Data": { "comment": "Intento de entrega no exitoso: destinatario ausente", "evidence": [ "https://example.com/evidence/unsuccessful-delivery.jpg" ] } }, { "StatusCode": "3001", "StatusName": "stored", "Category": "", "CreatedAt": "2023-01-05 22:00:00", "Data": { "comment": "Paquete recibido en estación después del intento de entrega", "evidence": [] } }, { "StatusCode": "5001", "StatusName": "onRoadToReturn", "Category": "", "CreatedAt": "2023-01-06 15:00:00", "Data": { "comment": "Paquete asignado a ruta de devolución al remitente", "evidence": [] } }, { "StatusCode": "5101", "StatusName": "unsuccessfulReturn", "Category": "", "CreatedAt": "2023-01-06 18:30:00", "Data": { "comment": "Intento de devolución no exitoso: establecimiento del remitente cerrado", "evidence": [ "https://example.com/evidence/unsuccessful-return.jpg" ] } } ] } ``` ## Request body - object - `url` string, uri, required: Url of the webhook. Must start with https:// - `headers` object: Map of custom headers. Max 3 headers ## Response `200` Config Response - object - `status` integer - `message` string - `data` object - `status_rules` object - `status_rules` integer - `allowed_status_names` string[] - `headers` object - `Authorization` string - `Content-Type` string - `User-Agent` string - `id` string - `owner` object - `client_id` string - `url` string ## Changes - **2026-11-03** `d05ecf04ecbe`: 1 info - endpoint added [Operation history](https://skmtc.dev/99minutos/apis/api-version-3/changes/api/v3/webhooks/post.md) --- [API](https://skmtc.dev/99minutos/apis/api-version-3.md) - [All operations](https://skmtc.dev/99minutos/apis/api-version-3/llms.txt) - [OpenAPI document](https://skmtc.dev/99minutos/apis/api-version-3/revisions/d05ecf04ecbe?raw)