> ## Documentation Index
> Fetch the complete documentation index at: https://terminal49-feat-trade-intel-sdk.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a webhook

> Register a new webhook endpoint with the Terminal49 API to receive real-time notifications for tracking request, shipment, and container event changes.



## OpenAPI

````yaml post /webhooks
openapi: 3.0.0
info:
  title: Terminal49 API Reference
  version: 0.2.0
  contact:
    name: Terminal49 API support
    url: https://www.terminal49.com
    email: support@terminal49.com
  description: >-
    The Terminal 49 API offers a convenient way to programmatically track your
    shipments from origin to destination.


    Please enter your API key into the "Variables" tab before using these
    endpoints within Postman.
  x-label: Beta
  termsOfService: https://www.terminal49.com/terms
servers:
  - url: https://api.terminal49.com/v2
    description: Production
security:
  - authorization: []
tags:
  - name: Containers
  - name: Custom Field Definitions
  - name: Custom Field Options
  - name: Custom Fields
  - name: Shipments
  - name: Locations
  - name: Events
  - name: Tracking Requests
  - name: Webhooks
  - name: Webhook Notifications
  - name: Ports
  - name: Metro Areas
  - name: Terminals
  - name: Routing (Paid)
  - name: Documents
  - name: Email Submissions
  - name: Document Schemas
  - name: Search
  - name: Parties
  - name: Trade Intelligence
    description: >-
      Trade intelligence answers questions about who imports what into the US,
      from where, on which carriers, and how that changes over time. The data is
      US import bill-of-lading records (US Customs vessel manifests): every
      ocean container landed at a US port (plus US-bound cargo landed at
      Vancouver, BC) from January 2022 to today, refreshed daily. It does not
      include air freight, exports, or domestic moves.


      **Access.** Trade intelligence is enabled per account. Accounts without it
      receive `403 Forbidden` with `{"error": "Trade intelligence is not enabled
      for this account"}`; contact sales@terminal49.com to enable it. Requests
      are limited to roughly 120 per minute per account (`429` with `{"error":
      "Rate limit exceeded; retry in a minute"}`).


      **Format.** These endpoints accept and return plain JSON, not JSON:API.
      Send `Content-Type: application/json` on `POST` requests and authenticate
      exactly like every other v2 endpoint (`Authorization: Token
      YOUR_API_KEY`).


      **Typical flow.** Resolve a name or product first, then analyze:
      `companies/search` or `commodities/search` give you the exact
      `company_name` or `hs4` to pass to `companies/profile`, `importers/top`,
      `trends`, or `breakdown`. Container and bill of lading numbers go straight
      to `containers/lookup` and `bills_of_lading/lookup`.


      **Reading the numbers.**


      - **Volume is physical containers.** Each box is counted once, even when
      it appears on several bills of lading. A container carrying several HS
      codes counts once per code and companies can share containers, so do not
      add volumes across HS codes or companies; take market totals from `trends`
      or `breakdown` without a company filter.

      - **Estimated value is a modelled USD estimate**, not the declared customs
      value.

      - **The current month is partial.** `trends` and `breakdown` include it by
      default; `companies/profile` and `importers/top` use full calendar months.
      Compare full months against the same months a year earlier.

      - **Absent volume is not small volume.** Importers can ask US Customs to
      withhold their name from manifests, and much large-retail freight is
      booked under forwarders or suppliers. Treat a company's figures as a
      floor, never as its size.

      - **One company, many names.** Company names are normalized but split by
      state, and large importers use several names (distribution, merchandising,
      and DC entities). Related entities are separate companies; report them
      separately. `companies/search` ranks by match quality, not by size.

      - **Companies are the consignee or notify party on the bill.** Forwarders,
      NVOCCs, and customs brokers appear alongside cargo owners. A high
      notify-party share, or LOGISTICS, FREIGHT, SHIPPING, CUSTOMS, or BROKERAGE
      in the name, usually indicates a logistics provider.

      - **Carriers, countries, and ports use the manifests' spellings**, and
      carriers appear under spelling variants (for example `CMA CGM` and `CMA
      CGM AMERICA LLC`). Filter with substrings and merge variants before
      computing shares.

      - **HS4 descriptions are truncated.** Check `common_goods` from
      `commodities/search` before relying on a code.
paths:
  /webhooks:
    parameters: []
    post:
      tags:
        - Webhooks
      summary: Create a webhook
      description: >-
        You can configure a webhook via the API to be notified about events that
        happen in your Terminal49 account. These events can be realted to
        tracking_requests, shipments and containers. 


        This is the recommended way tracking shipments and containers via the
        API. You should use this instead of polling our the API periodically.  
      operationId: post-webhooks
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  required:
                    - attributes
                    - type
                  properties:
                    attributes:
                      type: object
                      required:
                        - url
                        - active
                      properties:
                        url:
                          type: string
                          example: >-
                            https://webhook.site/#!/39084fbb-d887-42e8-be08-b9183ad02362
                          format: uri
                          description: The URL of the webhook endpoint.
                        events:
                          type: array
                          uniqueItems: true
                          description: The list of events to enable for this endpoint.
                          minItems: 1
                          items:
                            type: string
                            enum:
                              - container.transport.vessel_arrived
                              - container.transport.estimated.vessel_arrived
                              - container.transport.vessel_discharged
                              - container.transport.vessel_loaded
                              - container.transport.vessel_departed
                              - container.transport.estimated.vessel_departed
                              - container.transport.rail_departed
                              - container.transport.rail_arrived
                              - container.transport.rail_loaded
                              - container.transport.rail_unloaded
                              - container.transport.transshipment_arrived
                              - container.transport.transshipment_discharged
                              - container.transport.transshipment_loaded
                              - container.transport.transshipment_departed
                              - container.transport.feeder_arrived
                              - container.transport.feeder_discharged
                              - container.transport.feeder_loaded
                              - container.transport.feeder_departed
                              - container.transport.empty_out
                              - container.transport.full_in
                              - container.transport.full_out
                              - container.transport.empty_in
                              - container.transport.vessel_berthed
                              - shipment.estimated.arrival
                              - tracking_request.succeeded
                              - tracking_request.failed
                              - tracking_request.awaiting_manifest
                              - tracking_request.tracking_stopped
                              - container.created
                              - container.updated
                              - container.pod_terminal_changed
                              - >-
                                container.transport.arrived_at_inland_destination
                              - >-
                                container.transport.estimated.arrived_at_inland_destination
                              - container.pickup_lfd.changed
                              - container.pickup_lfd_line.changed
                              - container.pickup_lfd_terminal.changed
                              - container.pickup_lfd_rail.changed
                              - container.pickup_appointment.changed
                              - container.transport.available
                              - container.transport.not_available
                              - container.transport.delivered
                              - document_representation.created
                              - document_representation.failed
                            example: tracking_request.succeeded
                        active:
                          type: boolean
                        headers:
                          type: array
                          description: >-
                            Optional custom headers to pass with each webhook
                            invocation
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                                description: >-
                                  The name of the header. (Please note this will
                                  be auto-capitalized) 
                              value:
                                type: string
                                description: |
                                  The value to pass for the header
                    type:
                      type: string
                      enum:
                        - webhook
              required:
                - data
            examples:
              Test Webhook (all events):
                value:
                  data:
                    attributes:
                      url: https://webhook.site/
                      events:
                        - container.transport.vessel_arrived
                        - container.transport.estimated.vessel_arrived
                        - container.transport.vessel_discharged
                        - container.transport.vessel_loaded
                        - container.transport.vessel_departed
                        - container.transport.estimated.vessel_departed
                        - container.transport.rail_departed
                        - container.transport.rail_arrived
                        - container.transport.rail_loaded
                        - container.transport.rail_unloaded
                        - container.transport.transshipment_arrived
                        - container.transport.transshipment_discharged
                        - container.transport.transshipment_loaded
                        - container.transport.transshipment_departed
                        - container.transport.feeder_arrived
                        - container.transport.feeder_discharged
                        - container.transport.feeder_loaded
                        - container.transport.feeder_departed
                        - container.transport.empty_out
                        - container.transport.full_in
                        - container.transport.full_out
                        - container.transport.empty_in
                        - container.transport.vessel_berthed
                        - shipment.estimated.arrival
                        - tracking_request.succeeded
                        - tracking_request.failed
                        - tracking_request.awaiting_manifest
                        - tracking_request.tracking_stopped
                        - container.created
                        - container.updated
                        - container.pod_terminal_changed
                        - container.transport.arrived_at_inland_destination
                        - >-
                          container.transport.estimated.arrived_at_inland_destination
                        - container.pickup_lfd.changed
                        - container.pickup_lfd_line.changed
                        - container.pickup_lfd_terminal.changed
                        - container.pickup_lfd_rail.changed
                        - container.pickup_appointment.changed
                        - container.transport.available
                        - container.transport.not_available
                        - container.transport.delivered
                      active: true
                    type: webhook
        description: ''
      responses:
        '201':
          description: Create a test webhook endpoint
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/webhook'
              examples:
                Test Endpoint Created:
                  value:
                    data:
                      type: webhook
                      id: 9809fb96-7754-488f-99df-29ca8d410d89
                      attributes:
                        url: https://webhook.site/
                        active: true
                        events:
                          - tracking_request.succeeded
                        secret: WEBHOOK_SECRET_PLACEHOLDER
                        created_at: '2020-06-05T19:06:13Z'
            application/xml:
              schema:
                $ref: '#/components/schemas/webhook'
components:
  schemas:
    webhook:
      title: webhook
      type: object
      x-examples: {}
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - webhook
        attributes:
          type: object
          properties:
            url:
              type: string
              format: uri
              description: https end point
            active:
              type: boolean
              default: true
              description: Whether the webhook will be delivered when events are triggered
            events:
              type: array
              description: The list of events to enabled for this endpoint
              uniqueItems: true
              minItems: 1
              items:
                type: string
                enum:
                  - container.transport.vessel_arrived
                  - container.transport.estimated.vessel_arrived
                  - container.transport.vessel_discharged
                  - container.transport.vessel_loaded
                  - container.transport.vessel_departed
                  - container.transport.estimated.vessel_departed
                  - container.transport.rail_departed
                  - container.transport.rail_arrived
                  - container.transport.rail_loaded
                  - container.transport.rail_unloaded
                  - container.transport.transshipment_arrived
                  - container.transport.transshipment_discharged
                  - container.transport.transshipment_loaded
                  - container.transport.transshipment_departed
                  - container.transport.feeder_arrived
                  - container.transport.feeder_discharged
                  - container.transport.feeder_loaded
                  - container.transport.feeder_departed
                  - container.transport.empty_out
                  - container.transport.full_in
                  - container.transport.full_out
                  - container.transport.empty_in
                  - container.transport.vessel_berthed
                  - shipment.estimated.arrival
                  - tracking_request.succeeded
                  - tracking_request.failed
                  - tracking_request.awaiting_manifest
                  - tracking_request.tracking_stopped
                  - container.created
                  - container.updated
                  - container.pod_terminal_changed
                  - container.transport.arrived_at_inland_destination
                  - container.transport.estimated.arrived_at_inland_destination
                  - container.pickup_lfd.changed
                  - container.pickup_lfd_line.changed
                  - container.pickup_lfd_terminal.changed
                  - container.pickup_lfd_rail.changed
                  - container.pickup_appointment.changed
                  - container.transport.available
                  - container.transport.not_available
                  - container.transport.delivered
                  - document_representation.created
                  - document_representation.failed
            secret:
              type: string
              description: A random token that will sign all delivered webhooks
            headers:
              type: array
              nullable: true
              items:
                type: object
                properties:
                  name:
                    type: string
                  value:
                    type: string
          required:
            - url
            - active
            - events
            - secret
      required:
        - id
        - type
      description: ''
  securitySchemes:
    authorization:
      name: Authorization
      type: apiKey
      in: header
      description: >-
        Use a Terminal49 API key in the `Authorization` header with the `Token`
        prefix.


        `Authorization: Token YOUR_API_KEY`

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.