webhook Webhook Events

Event Payload Envelope link

Every current webhook event is delivered as a JSON object carrying event_type, ref and timestamp, plus an optional __info object holding resource details.

__info is omitted entirely for events that carry no resource details — it is not sent as an empty object. Read it defensively (payload.get("__info", {}) rather than payload["__info"]); the index table marks which events include it.

The deprecated INVOICE_BLOCK_STATUS_UPDATED event predates this envelope and uses a different, legacy shape.

In every table on this page, the Optional column reads X = always present, O = not present on every event (the Description says which events carry it). A field that is present can still be null.

{
  "event_type": "invoice.created",
  "ref": "invoice_ref",
  "timestamp": 1691535792.22,
  "__info": {
    "invoice_no": "Invoice NO."
  }
}

Supported Webhook Event Types link

The table below lists the webhook event types GoFreight emits. Use the event_type string verbatim in the event_types array when you register a subscription.

The __info column links to the field definitions for that resource. — means the event carries no __info.

Event Payload Details link

Each section below covers one resource: the __info fields its events carry, plus an example payload. Every event also carries the envelope fields event_type, ref and timestamp; where a resource has no __info, the example shows the envelope alone.

Optional column: X = always present, O = not present on every event of this resource — the Description names the events that carry it. A present field can still be null.

Ocean B/L Events link

oi_mbl.*, oi_hbl.*, oe_mbl.*, oe_hbl.* carry no __info. ref is the MB/L or HB/L reference ID.

{
  "event_type": "oi_mbl.created",
  "ref": "mbl_ref",
  "timestamp": 1706337141.0
}

Invoice Events link

{
  "event_type": "invoice.voided",
  "ref": "invoice_ref",
  "timestamp": 1691535792.22,
  "__info": {
    "invoice_no": "Invoice NO.",
    "is_void": true,
    "void_date": "2024-04-12"
  }
}

Payment Events link

payment.* events carry no __info. ref is the payment reference ID.

{
  "event_type": "payment.created",
  "ref": "payment_ref",
  "timestamp": 1691535792.22
}

Container Events link

{
  "event_type": "container.updated",
  "ref": "container_ref",
  "timestamp": 1691535792.22,
  "__info": {
    "container_no": "Container NO.",
    "updated_fields": ["field_name"]
  }
}

Trade Partner Events link

For trade partner events, ref is the trade partner code, not a numeric reference ID.

updated_fields reports public API field names rather than the raw names those fields are stored under — an office change is reported as office, and address fields are dot-notated (address.country, address.phone, address.zip_code). When any field feeding the printed address changes, the derived address.print_address and address.billing_address are appended as well.

{
  "event_type": "trade_partner.merged",
  "ref": "TP code 1",
  "timestamp": 1691535792.22,
  "__info": {
    "readable_name": "TP Name 1",
    "merged_from_code": "TP code 2",
    "merged_from_name": "TP Name 2"
  }
}

Billing Code Events link

{
  "event_type": "billing_code.updated",
  "ref": "billing_code_ref",
  "timestamp": 1691535792.22,
  "__info": {
    "readable_name": "code",
    "updated_fields": ["name", "general_ledgers.revenue"]
  }
}

General Ledger Code Events link

{
  "event_type": "general_ledger_code.updated",
  "ref": "general_ledger_code_ref",
  "timestamp": 1691535792.22,
  "__info": {
    "readable_name": "code",
    "updated_fields": ["code", "is_active"]
  }
}

Deprecated Events link

⚠️ Invoice Block Status Updated Event link

{
  "event_type": "INVOICE_BLOCK_STATUS_UPDATED",
  "timestamp": 1691535792.22,
  "invoice": {
    "ref": "invoice_ref",
    "invoice_no": "invoice_no",
    "system_no": "system_no",
    "customer_ref_no": "customer_ref_no",
    "type": "S",
    "amount": "123.23",
    "paid_amount": "0",
    "tax_amount": "10.00",
    "process_state": "N",
    "post_date": "2023-07-31T20:35:03",
    "due_date": "2023-08-01T20:35:03",
    "is_block": true,
    "block_by": {
      "ref": 3,
      "username": "block by username"
    },
    "block_date": "2023-08-22",
    "is_general_expense": false,
    "remark": "some description",
    "lines": [
      {
        "ref": 54140,
        "name": "ISF FILING FEE",
        "type": "B",
        "freight_term": "C",
        "unit": "UNT",
        "link_type": "AP-OC",
        "currency": {
          "ref": 1,
          "name": "USD"
        },
        "currency_amount": "123.23",
        "volume": "12",
        "rate": "28.27",
        "amount": "339.24",
        "billing_code": {
          "ref": 121,
          "code": "OI07ISF",
          "name": "ISF FILING FEE",
          "general_ledger_code": {
            "ref": 157,
            "code": "45406",
            "type": "CO"
          }
        },
        "tax": {
          "name": "tax_name",
          "type": "S",
          "rate": "10.0"
        }
      }
    ]
  },
  "creator": {
    "ref": "user_ref",
    "username": "user name",
    "email": "user email"
  },
  "trade_partner": {
    "ref": "tp_ref",
    "type": "CS",
    "name": "tp name",
    "local_name": "tp local name",
    "short_name": "tp short name"
  },
  "mbl": {
    "ref": "mbl_ref",
    "transportation_mode": "OI",
    "mbl_no": "mbl no"
  },
  "hbl": {
    "ref": "new_hbl_ref",
    "transportation_mode": "OI",
    "hbl_no": "hbl no"
  },
  "office": {
    "ref": "office_ref",
    "short_name": "office short name",
    "full_name": "office full name",
    "local_name": "office local name"
  }
}