{
  "openapi": "3.1.0",
  "info": {
    "title": "Webhooks",
    "version": "1.0.0",
    "description": "**Outbound webhooks** from Cargobase to HTTPS endpoints you host.\n\nUse this when you want push updates (e.g. shipment/tracking events) instead of polling production (https://pluto.cargobase.com). Return `2xx` to acknowledge delivery.\n\n## What’s in this API\n\n| Section | What it’s for |\n| --- | --- |\n| **Webhooks** | Outbound event payloads Cargobase POSTs to your webhook URL. |\n| **Models** | Shared schemas for those event payloads. |"
  },
  "webhooks": {
    "shipmentUpdate": {
      "post": {
        "summary": "Shipment Update",
        "description": "Tracking event information is sent to the webhook whenever tracking updates enter Cargobase.\n## Sample JSON\n ```json\n{\n    \"tracking_number\": \"TG166222\",\n    \"tracking_status_tag\": \"DELIVERED\",\n    \"event_time\": \"2023-07-01T14:59:56.711\",\n    \"event_time_with_timezone\": \"2032-04-23T10:20:30.400+02:30\",\n    \"bill_of_lading\": {\n        \"bill_of_lading_number\": \"COSU6349613240\",\n        \"carrier_no\": \"COSU\",\n        \"container_no\": \"BMOU1589176\"\n    },\n    \"location\": {\n        \"country_code\": \"US\",\n        \"state\": \"Arkansas\"\n    },\n    \"document_link\": \"https://getsamplefiles.com/filedownloadhere\"\n}\n```",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ShipmentUpdateEvent"
              },
              "examples": {
                "delivered": {
                  "summary": "Delivered",
                  "value": {
                    "tracking_number": "TG166222",
                    "external_shipment_id": "S12345678",
                    "tracking_status_tag": "DELIVERED",
                    "event_time": "2026-10-10T16:40:00.000Z",
                    "document_link": "https://example.com/pod/TG166222.pdf",
                    "location": {
                      "country_code": "NL"
                    }
                  }
                },
                "inTransit": {
                  "summary": "In transit",
                  "value": {
                    "tracking_number": "TG166222",
                    "external_shipment_id": "S12345678",
                    "tracking_status_tag": "INTRANSIT",
                    "event_time": "2026-10-08T10:20:00.000Z",
                    "location": {
                      "country_code": "SG"
                    }
                  }
                },
                "ocean": {
                  "summary": "Ocean bill of lading",
                  "value": {
                    "tracking_number": "COSU6349613240",
                    "external_shipment_id": "S12345678",
                    "tracking_status_tag": "INTRANSIT",
                    "event_time": "2026-10-09T06:00:00.000Z",
                    "bill_of_lading": {
                      "bill_of_lading_number": "COSU6349613240",
                      "carrier_no": "COSU",
                      "container_no": "BMOU1589176"
                    },
                    "location": {
                      "country_code": "SG"
                    }
                  }
                },
                "estimatedArrival": {
                  "summary": "Estimated arrival",
                  "value": {
                    "tracking_number": "TG166222",
                    "external_shipment_id": "S12345678",
                    "tracking_status_tag": "EST_ARRIVAL",
                    "event_time": "2026-10-12T18:00:00.000Z"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook received successfully. Return 2xx to acknowledge delivery."
          }
        },
        "operationId": "shipmentUpdateWebhook",
        "tags": [
          "Webhooks"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ShipmentUpdateEvent": {
        "type": "object",
        "description": "Shipment update payload schema",
        "required": [
          "tracking_number",
          "external_shipment_id",
          "tracking_status_tag"
        ],
        "properties": {
          "tracking_number": {
            "type": "string",
            "example": "TG166222",
            "description": "Tracking number of the shipment"
          },
          "external_shipment_id": {
            "type": "string",
            "example": "testshipmentid",
            "description": "Shipment ID used to identify shipment in external systems"
          },
          "tracking_status_tag": {
            "type": "string",
            "description": "Current status tag of the tracking event, e.g., DELIVERED, IN_TRANSIT. For estimated events (EST_ARRIVAL, EST_PICKUP), the timestamps will be estimates of those events",
            "enum": [
              "BOOKED",
              "PICKUP",
              "INTRANSIT",
              "DELAYED",
              "DELIVERED",
              "CANCELLED",
              "UNSPECIFIED",
              "EST_ARRIVAL",
              "EST_PICKUP"
            ],
            "example": "DELIVERED"
          },
          "event_time": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of the event (local time) without timezone information.",
            "example": "2023-07-01T14:59:56.711"
          },
          "event_time_with_timezone": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of the event including timezone information (if available).",
            "example": "2023-04-23T10:20:30.400+02:30"
          },
          "bill_of_lading": {
            "type": "object",
            "description": "Details from the bill of lading associated with this tracking event. (only for ocean freight)",
            "properties": {
              "bill_of_lading_number": {
                "type": "string",
                "description": "Unique bill of lading number.",
                "example": "COSU6349613240"
              },
              "carrier_no": {
                "type": "string",
                "description": "SCAC carrier number or code.",
                "example": "COSU"
              },
              "container_no": {
                "type": "string",
                "description": "Container number associated with the shipment.",
                "example": "BMOU1589176"
              }
            }
          },
          "location": {
            "type": "object",
            "description": "JSON object containing location information where the shipment update occurred",
            "properties": {
              "country_code": {
                "type": "string",
                "description": "ISO country code.",
                "example": "US"
              },
              "state": {
                "type": "string",
                "description": "State or province of the event location.",
                "example": "Arkansas"
              }
            }
          },
          "document_link": {
            "type": "string",
            "format": "uri",
            "description": "Link to a document related to this tracking event (e.g., POD, invoice).",
            "example": "https://getsamplefiles.com/filedownloadhere"
          }
        }
      }
    },
    "securitySchemes": {
      "TokenAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Token-based authentication (Django REST framework style).\n\nFormat: `Token <access_token>`\n\nExample: `Token your_token_here`"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Bearer token authentication (alternate).\n\nFormat: `Bearer <access_token>`\n\nExample: `Bearer your_token_here`"
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "paths": {},
  "servers": [
    {
      "url": "https://{customer-webhook-host}",
      "description": "Customer-managed webhook receiver URL",
      "variables": {
        "customer-webhook-host": {
          "default": "hooks.example.com",
          "description": "Hostname of the customer webhook endpoint"
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Webhooks",
      "description": "Events delivered to customer webhook endpoints"
    }
  ],
  "security": [
    {
      "TokenAuth": []
    },
    {
      "BearerAuth": []
    }
  ]
}