> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eazecustoms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Event reference

> Reference guide for all Eaze Customs webhook event types and their payloads.

This page describes the event types sent by Eaze Customs webhooks and lists their payload structures.

## Event payload structure

Every webhook delivery contains a JSON object with the following top-level fields:

| Field     | Type   | Description                 |
| :-------- | :----- | :-------------------------- |
| `event`   | string | The name of the event type. |
| `payload` | object | The event-specific details. |

***

## Declaration events

These events trigger during the customs lifecycle of a declaration.

### `declaration.created`

Occurs when you successfully create a new declaration.

#### Payload fields

| Field                 | Type   | Description                                               |
| :-------------------- | :----- | :-------------------------------------------------------- |
| `declarationId`       | number | The unique identifier of the declaration.                 |
| `lrn`                 | string | The Local Reference Number.                               |
| `commercialReference` | string | The Commercial Reference (UCR).                           |
| `statusCode`          | string | The status code of the declaration, initialized to `new`. |
| `createdAt`           | string | The date-time when the declaration was created.           |

#### Example payload

```json theme={null}
{
  "event": "declaration.created",
  "payload": {
    "declarationId": 1024,
    "lrn": "LRN-IMPORT-9988A",
    "commercialReference": "UCR-88776655",
    "statusCode": "new",
    "createdAt": "2026-06-23T12:00:00.000Z"
  }
}
```

### `declaration.status_updated`

Occurs when the customs status of a declaration is updated.

#### Payload fields

| Field           | Type   | Description                                                                                       |
| :-------------- | :----- | :------------------------------------------------------------------------------------------------ |
| `declarationId` | number | The unique identifier of the declaration.                                                         |
| `status`        | string | The new status code value. See [Declaration status codes](#declaration-status-codes) for details. |
| `timestamp`     | string | The date-time when the status change occurred.                                                    |

#### Declaration status codes

The `status` field contains one of the following values:

* `new` — The declaration has just been created.
* `readyToDeclare` — The data is complete and ready to declare.
* `prelodged` — The advance declaration has been submitted.
* `registered` — The declaration has been registered with customs.
* `presentation` — The presentation notification has been sent.
* `acknowledged` — The declaration has been legally accepted.
* `control` — The declaration is under document or physical control.
* `invalid` — The declaration is invalid.
* `blocked` — The declaration has technical errors.
* `released` — The goods have been cleared by customs.
* `norelease` — The goods are not cleared.
* `finalTaxNotice` — The final customs tax decision is issued.
* `completed` — The customs process is finalized.
* `canceled` — The declaration is canceled.

#### Example payload

```json theme={null}
{
  "event": "declaration.status_updated",
  "payload": {
    "declarationId": 1024,
    "status": "released",
    "timestamp": "2026-06-23T12:05:00.000Z"
  }
}
```

### `declaration.completed`

Occurs when the customs clearance process is fully completed.

#### Payload fields

| Field              | Type   | Description                                                 |
| :----------------- | :----- | :---------------------------------------------------------- |
| `declarationId`    | number | The unique identifier of the declaration.                   |
| `lrn`              | string | The Local Reference Number.                                 |
| `mrn`              | string | The Master Reference Number issued by customs.              |
| `statusCode`       | string | The status code of the declaration, which is `completed`.   |
| `customsClearedAt` | string | The date-time when customs cleared the declaration.         |
| `completedAt`      | string | The date-time when the declaration was marked as completed. |

#### Example payload

```json theme={null}
{
  "event": "declaration.completed",
  "payload": {
    "declarationId": 1024,
    "lrn": "LRN-IMPORT-9988A",
    "mrn": "26NL9876543210M123",
    "statusCode": "completed",
    "customsClearedAt": "2026-06-23T12:10:00.000Z",
    "completedAt": "2026-06-23T12:15:00.000Z"
  }
}
```

### `declaration.invalidated`

Occurs when a declaration is invalidated by customs.

#### Payload fields

| Field           | Type   | Description                                             |
| :-------------- | :----- | :------------------------------------------------------ |
| `declarationId` | number | The unique identifier of the declaration.               |
| `lrn`           | string | The Local Reference Number.                             |
| `mrn`           | string | The Master Reference Number.                            |
| `statusCode`    | string | The status code of the declaration, which is `invalid`. |
| `invalidatedAt` | string | The date-time when the declaration was invalidated.     |
| `reason`        | string | The invalidation reason provided by customs.            |

#### Example payload

```json theme={null}
{
  "event": "declaration.invalidated",
  "payload": {
    "declarationId": 1024,
    "lrn": "LRN-IMPORT-9988A",
    "mrn": "26NL9876543210M123",
    "statusCode": "invalid",
    "invalidatedAt": "2026-06-23T12:20:00.000Z",
    "reason": "Exporter request for cancellation before presentation."
  }
}
```

### `declaration.error`

Occurs when a declaration fails validation or receives an error from customs.

#### Payload fields

| Field           | Type   | Description                                                                  |
| :-------------- | :----- | :--------------------------------------------------------------------------- |
| `declarationId` | number | The unique identifier of the declaration.                                    |
| `lrn`           | string | The Local Reference Number.                                                  |
| `errorType`     | string | The type of error (for example, `INT_XML`, `CUSTOMS_XML`, or `CUSTOMS_ERR`). |
| `errorMessage`  | string | The detailed description of the error.                                       |
| `timestamp`     | string | The date-time when the error occurred.                                       |

#### Example payload

```json theme={null}
{
  "event": "declaration.error",
  "payload": {
    "declarationId": 1024,
    "lrn": "LRN-IMPORT-9988A",
    "errorType": "CUSTOMS_XML",
    "errorMessage": "Element 'CommodityCode': The value is not a valid HS code.",
    "timestamp": "2026-06-23T12:25:00.000Z"
  }
}
```

***

## Shipment events

These events trigger when you create or update shipments.

### `shipment.created`

Occurs when you successfully create a new shipment.

#### Payload fields

| Field          | Type   | Description                                  |
| :------------- | :----- | :------------------------------------------- |
| `shipmentId`   | number | The unique identifier of the shipment.       |
| `shipmentNo`   | string | The shipment reference number.               |
| `shipmentType` | string | The shipment type: `IMPORT` or `EXPORT`.     |
| `status`       | string | The shipment status, initialized to `new`.   |
| `createdAt`    | string | The date-time when the shipment was created. |

#### Example payload

```json theme={null}
{
  "event": "shipment.created",
  "payload": {
    "shipmentId": 2048,
    "shipmentNo": "SHP-2026-X100",
    "shipmentType": "IMPORT",
    "status": "new",
    "createdAt": "2026-06-23T12:00:00.000Z"
  }
}
```

### `shipment.updated`

Occurs when you update shipment details, such as weights, pricing, or status.

#### Payload fields

| Field          | Type   | Description                                                                        |
| :------------- | :----- | :--------------------------------------------------------------------------------- |
| `shipmentId`   | number | The unique identifier of the shipment.                                             |
| `shipmentNo`   | string | The shipment reference number.                                                     |
| `shipmentType` | string | The shipment type: `IMPORT` or `EXPORT`.                                           |
| `status`       | string | The current status of the shipment (`new`, `clearanceInProgress`, or `completed`). |
| `totalWeight`  | number | The total weight of the shipment.                                                  |
| `totalPrice`   | number | The total value/price of the shipment.                                             |
| `updatedAt`    | string | The date-time when the shipment was last updated.                                  |

#### Example payload

```json theme={null}
{
  "event": "shipment.updated",
  "payload": {
    "shipmentId": 2048,
    "shipmentNo": "SHP-2026-X100",
    "shipmentType": "IMPORT",
    "status": "clearanceInProgress",
    "totalWeight": 1450.50,
    "totalPrice": 25000.00,
    "updatedAt": "2026-06-23T12:30:00.000Z"
  }
}
```