# Coupling Webhooks

Coupling webhooks are triggered by events related to coupling Zimarkers.

## Overview

For coupling webhooks:

- `category`: `COUPLING`
- `triggerName`: One of the available coupling events (see below)
- `payload`: Contains the coupled pallet object or an error message


For complete webhook structure and field descriptions, see [Webhooks](/webhooks/webhooks).

## Available Events

- `COUPLING_SUCCEEDED` - Fired when a Zimarker is successfully coupled with a pallet ID
- `COUPLING_FAILED` - Fired when a Zimarker could not be coupled with a pallet ID


## Event Details

### 1. Coupling Succeeded Event

**Trigger**: `COUPLING_SUCCEEDED`

Fired when a Zimarker is successfully coupled with a pallet ID.


```json
{
    "category": "COUPLING",
    "eventIdentifier": "134a7982-acac-4b20-8464-c49aa6900832",
    "webhookUuid": "0ba817ee-bc3c-41c5-bd22-4b3f37e5620e",
    "triggerName": "COUPLING_SUCCEEDED",
    "triggerTime": 1783267221955,
    "entityExternalId": "LPN0001234599",
    "entityUuid": "327fbb17-2bbd-4587-bbf6-12cb2fc275c6",
    "operationId": "cd5efdca-e4ba-42e6-9cc2-1dd66a9bcb5c",
    "payload": {
        "uuid": "327fbb17-2bbd-4587-bbf6-12cb2fc275c6",
        "createDate": 1783267221625,
        "updateDate": 1783267221625,
        "deepLink": "https://67uo7.app.link/ysgphxjVw4b",
        "trackCode": "001-111",
        "wmsId": "LPN0001234599",
        "status": "ACTIVE",
        "zimarkCodes": [
            {
                "uuid": "ce71d0fb-177a-449c-b7e8-4345fd50966b",
                "zimarkMarkerValue": "89",
                "markerType": "ZMARKER",
                "coupledAt": 1783267221653
            }
        ],
        "manifests": []
    }
}
```

### 2. Coupling Failed Event

**Trigger**: `COUPLING_FAILED`

Fired when a Zimarker could not be coupled with a pallet ID.


```json
{
    "category": "COUPLING",
    "eventIdentifier": "3f4cdc9f-7e74-4924-862f-61dbe39b9a1c",
    "webhookUuid": "0ba817ee-bc3c-41c5-bd22-4b3f37e5620e",
    "triggerName": "COUPLING_FAILED",
    "triggerTime": 1783266610316,
    "entityExternalId": "LPN0001234599",
    "entityUuid": null,
    "operationId": "088869cf-883d-43ea-b620-e18395c5f002",
    "payload": {
        "failureReason": "Marker is being used in another track."
    }
}
```

## Payload Structure

For webhook header fields (category, eventIdentifier, triggerName, triggerTime, entityExternalId, entityUuid), see [Webhooks](/webhooks/webhooks).

### Coupling Success Payload

| Field | Type | Description |
|  --- | --- | --- |
| `uuid` | String | Track UUID |
| `createDate` | Long | Unix timestamp when the track was created |
| `updateDate` | Long | Unix timestamp when the track was last updated |
| `trackCode` | String | Track code identifier |
| `wmsId` | String | WMS identifier (your pallet ID) |
| `status` | String | Track status (ACTIVE, INACTIVE) |
| `deepLink` | String | Link to the Zimark Operational App |
| `zimarkCodes` | Array | The Zimarker(s) coupled to this track |
| `zimarkCodes[].uuid` | String | Zimarker UUID |
| `zimarkCodes[].zimarkMarkerValue` | String | The Zimarker code value |
| `zimarkCodes[].markerType` | String | Marker type used during coupling |
| `zimarkCodes[].coupledAt` | Long | Unix timestamp when coupled |
| `manifests` | Array | Manifests this Zimarker is part of |


### Coupling Failed Object

| Field | Type | Description |
|  --- | --- | --- |
| `failureReason` | String | Coupling error message |