Incidence webhooks

This documentation is for incidence webhooks version 2.

Mienvio sends two kinds of events about a shipment:

• shipment.status: changes to the shipment's status (picked up, in transit, delivered, etc.).
• shipment.incidence: anomalies reported by the carrier along the way (delay, wrong address, failed delivery attempt, etc.).

A shipment can have a normal status (e.g. "in transit") and one or more incidences at the same time. The status tells you where the shipment is; the incidence describes a specific problem detected on the way.

shipment.incidence uses exactly the same payload as shipment.status. The only differences are:

• type is "shipment.incidence".
• code and description carry the incidence code instead of the shipment status.
• A root-level incidence object (next to shipment) is added with the incidence details.

Activation

shipment.incidence is opt-in: it is not sent to any webhook automatically. To receive it, contact your Mienvio integration team or support to enable incidence notifications on your webhook. If you don't enable it, your endpoint keeps receiving only shipment.status.

Authentication and delivery

• Delivered to the same endpoint with the same authentication already configured for your webhook (API key, bearer token, OAuth2, etc.).
• Sent as POST with Content-Type: application/json.
• There are no automatic retries if your endpoint errors or doesn't respond. Respond with a 2xx quickly and process the event asynchronously.
• Each detected incidence is sent only once.

Payload example

{
    "type": "shipment.incidence",
    "version": "2.0",
    "trigger_time": "2026-10-07 12:19:51",
    "code": "delayed",
    "description": "delayed",
    "shipment": {
        "shipment_id": 7421546,
        "owner_id": 19629,
        "weight": 1,
        "length": 32,
        "width": 24,
        "height": 1,
        "volumetric_weight": "0.15",
        "real_weight": 1,
        "real_volumetric_weight": 0,
        "real_length": 0,
        "real_width": 0,
        "real_height": 0,
        "declared_value": 0,
        "description": "411329",
        "external_order_id": null,
        "created_at": "2026-10-01 09:00:00",
        "updated_at": "2026-10-07 12:19:51",
        "address_from": { "...": "same as shipment.status" },
        "address_to": { "...": "same as shipment.status" },
        "label": { "...": "same as shipment.status" },
        "purchase": { "...": "same as shipment.status" },
        "rate": { "...": "same as shipment.status" },
        "events": [
            {
                "date": "2026-10-06",
                "time": "17:16:12",
                "date_time": "2026-10-06 17:16:12",
                "description": "Shipment picked up",
                "code": "picked_up",
                "area": "",
                "is_service_incident": false,
                "is_pickup_exception": false,
                "is_in_return_process": false
            }
        ]
    },
    "incidence": {
        "code": "delayed",
        "description": "Paquete retrasado por alto volumen en centro de distribución",
        "place_name": "CDMX",
        "occurred_at": "2026-09-09 13:58:00"
    }
}

See the Webhooks page for the full shipment object (address_from, address_to, label, purchase, rate). events[] keeps the full tracking history; the per-event flags is_service_incident, is_pickup_exception and is_in_return_process are unchanged.

incidence object

Incidence code catalog

This catalog may grow. Your integration should handle unknown codes safely (e.g. showing the raw value) instead of rejecting the event.

FAQ

Can I receive shipment.status and shipment.incidence on the same endpoint?
Yes. They share endpoint, credentials and payload structure; tell them apart with the type field.

Why does the payload include all the shipment data?
So you can reuse the same parser you use for shipment.status. If you only care about the incidence, read the incidence object and ignore the rest.