Olay Türleri

Bu parametre, ilgili webhook isteğinin hangi olay esnasında tetikleneceğini ve iletileceğini belirtir.

Enum Sınıf Adı: WebhookSubscribedEvent
Parametre Adı: subscribedEvent

Değer	Açıklama
consignment.size.updated	Sevkiyat boyut bilgileri güncellendiğinde tetiklenir
consignment.status.updated	Sevkiyat durumu güncellendiğinde tetiklenir
consignment.label.created	Sevkiyata yeni label eklendiğinde tetiklenir
package.status.updated	Paketin durumu veya durum mesajı değiştiğinde tetiklenir
package.size.updated	Paketin ağırlık, desi veya ölçüleri değiştiğinde tetiklenir

Bu değerler, hem webhook oluşturulurken hem de yanıt verirken kullanılabilir. Kendi sisteminize dahil ederek entegrasyonu ve anlaşılabilirliği artırabilirsiniz.

Webhook Payload Örnekleri

Aşağıda her olay türü için webhook'un sisteminize göndereceği örnek payload'lar bulunmaktadır.

Bu örnekler varsayılan JSON payload'ı gösterir. Tarihler RFC 3339 biçimindedir ve timezone offset içerir. Tarihler ve offset dahil tüm değerler örnek veridir.

consignment.status.updated

Sevkiyat durumu güncellendiğinde tetiklenir. triggerEvent, webhook'u tetikleyen olayı taşır (id, status, statusMessage, statusUpdatedAt, location, originalStatus, packageId). Bu olay bir pakete aitse triggerEvent.packageId ilgili paketi belirtir; değilse null olur. Webhook belirli bir olaya bağlı olmadan yeniden gönderildiğinde triggerEvent alanı bulunmaz. Paket olayları bu event'i tetiklemeye devam eder; package.status.updated buna ek olarak gönderilir.

{
  "headers": {
    "Authorization": "__YOUR_AUTH_KEY__",
    "Content-Type": "application/json"
  },
  "body": {
    "event": "consignment.status.updated",
    "data": {
      "consignmentId": 3396107,
      "consignmentUuid": "8378bbe5-b66c-4048-bf9d-b4cd52469bec",
      "barcode": "C2H04729482615",
      "referenceNo": "KPTT1661447TDBZP",
      "location": null,
      "status": 1,
      "statusMessage": "Consignment sent to provider",
      "statusUpdatedAt": "2025-10-31T13:09:16+03:00",
      "lastTrackingCode": "KPTT1661447TDBZP",
      "createdAt": "2025-10-31T13:09:16+03:00",
      "events": [
        {
          "status": 1,
          "statusMessage": "Consignment sent to provider",
          "statusUpdatedAt": "2025-10-31T13:09:16+03:00",
          "location": null
        }
      ],
      "labels": [],
      "triggerEvent": {
        "id": 18734521,
        "status": 1,
        "statusMessage": "Consignment sent to provider",
        "statusUpdatedAt": "2025-10-31T13:09:16+03:00",
        "location": null,
        "originalStatus": null,
        "packageId": null
      }
    }
  }
}

consignment.label.created

Gönderiye yeni label eklendiğinde tetiklenir. Label'ın bağlı olduğu paketin bilgilerini ve varsa yerine geçtiği önceki label'ı bildirir.

Alan	Tip	Açıklama
`package.packageId`	integer veya null	Label'ın bağlı olduğu paketin ID'si. ID yoksa `null` gönderilir.
`package.weight`, `package.length`, `package.width`, `package.height`, `package.desi`	number	Label'ın bağlı olduğu paketin kayıtlı ağırlık, boyut ve desi bilgileri.
`replacedLabel`	object veya null	Değiştirilen önceki label'ın `trackingCode` ve `trackingType` bilgileri. Değiştirme bilgisi yoksa `null` gönderilir. Önceki takip kodu ve tipi de `null` olabilir.
`trackingType`	integer veya null	`1`: barkod/takip kodu; `2`: referans numarası; `null`: tip tanımlı değil.
`createdAt`, `updatedAt`	datetime string	Label'ın oluşturulma ve güncellenme tarihleri.

package nesnesi her zaman gönderilir. Label'a bağlı paket yoksa packageId alanı null, ölçüler 0 olur. Tanımlanmamış ölçüler de 0 olarak gönderilir. Ölçüler, event oluşturulduğu anda pakette kayıtlı olan değerlerdir.

replacedLabel: null tek başına yeni paket oluşturulduğunu belirtmez. İlgili paket package.packageId ile belirlenir.

Örnek: ek bir paketin label'ı

Bu örnekte 41 ID'li paket alıcı sistem için yenidir ve bir label'ın yerine geçilmemiştir.

{
  "headers": {
    "Authorization": "__YOUR_AUTH_KEY__",
    "Content-Type": "application/json"
  },
  "body": {
    "event": "consignment.label.created",
    "data": {
      "consignmentId": 3393215,
      "consignmentUuid": "8f5ad2c9-3a2a-4e7d-a858-d1b9e17fd15d",
      "barcode": "2791937361446",
      "referenceNo": "EPTT898824753",
      "trackingCode": "2791937361446",
      "trackingType": 2,
      "provider": "Ptt",
      "replacedLabel": null,
      "package": {
        "packageId": 41,
        "weight": 1.4,
        "length": 0,
        "width": 0,
        "height": 0,
        "desi": 3
      },
      "createdAt": "2026-10-12T10:00:00+03:00",
      "updatedAt": "2026-10-12T10:00:00+03:00",
      "base64label": "__BASE64_DATA__"
    }
  }
}

Örnek: referans label'ının yerine barkod gelmesi

Aynı 41 ID'li paketin referans label'ı (trackingType: 2) yerine takip barkodu (trackingType: 1) gelir. Önceki label'ın bilgileri replacedLabel içinde gönderilir.

{
  "headers": {
    "Authorization": "__YOUR_AUTH_KEY__",
    "Content-Type": "application/json"
  },
  "body": {
    "event": "consignment.label.created",
    "data": {
      "consignmentId": 3393215,
      "consignmentUuid": "8f5ad2c9-3a2a-4e7d-a858-d1b9e17fd15d",
      "barcode": "KP06696002342",
      "referenceNo": "EPTT898824753",
      "trackingCode": "KP06696002342",
      "trackingType": 1,
      "provider": "Ptt",
      "replacedLabel": {
        "trackingCode": "2791937361446",
        "trackingType": 2
      },
      "package": {
        "packageId": 41,
        "weight": 1.4,
        "length": 0,
        "width": 0,
        "height": 0,
        "desi": 3
      },
      "createdAt": "2026-10-12T11:00:00+03:00",
      "updatedAt": "2026-10-12T11:00:00+03:00",
      "base64label": "__BASE64_DATA__"
    }
  }
}

Örneklerdeki headers ve body anahtarları HTTP request'in bölümlerini gösterir. Request body içinde ek bir JSON katmanı değildir.

consignment.size.updated

Sevkiyat boyut bilgileri güncellendiğinde tetiklenir. weight ve desi alanları gönderinin toplamlarını taşır; paket miktarları bu toplamlara dahildir. Yeni paket eklenmesi bu toplamları değiştirirse de event gönderilir. Çok paketli gönderilerde weight ve desi, toplama dahil edilen paketlerin toplamıdır: iptal edilen paketler toplama dahil edilmez; en az bir paket kabul aldıktan sonra kabul almamış paketler de dahil edilmez. Tek bir paketin ölçüsü package.size.updated ile bildirilir.

{
  "headers": {
    "Authorization": "__YOUR_AUTH_KEY__",
    "Content-Type": "application/json"
  },
  "body": {
    "event": "consignment.size.updated",
    "data": {
      "consignmentId": 3393215,
      "consignmentUuid": "8f5ad2c9-3a2a-4e7d-a858-d1b9e17fd15d",
      "barcode": "C2H11294525102",
      "referenceNo": "EPTT898824753",
      "weight": 0.5,
      "length": 0,
      "width": 0,
      "height": 0,
      "desi": 1,
      "lastTrackingCode": "KP05917924760",
      "createdAt": "2025-10-31T13:09:16+03:00",
      "updatedAt": "2025-10-31T13:09:16+03:00",
      "events": [
        {
          "status": 1,
          "statusMessage": "Consignment sent to provider",
          "statusUpdatedAt": "2025-10-31T13:09:16+03:00",
          "location": null
        },
        {
          "status": 2,
          "statusMessage": "Kabul Edildi",
          "statusUpdatedAt": "2025-10-31T13:09:16+03:00",
          "location": "SAKARYA PKİM/SAKARYA PKİM"
        }
      ],
      "statusMessage": "Kabul Edildi",
      "status": 2
    }
  }
}

package.status.updated

Bir paketin durumu veya durum mesajı değiştiğinde, o paket için tetiklenir. Birden fazla paketi olan bir gönderide, değişen her paket için ayrı bir webhook gönderilir.

Webhook yalnızca paketin durumu veya durum mesajı gerçekten değiştiğinde gönderilir. Kargo firmasından aynı durumla tekrar gelen olaylar yeniden gönderilmez.
Kargo firması tarafından eklenen bir paket (örneğin gönderi için yeni bir takip barkodu geldiğinde) oluşturulduğu anda webhook göndermez. İlk durumunu aldığında ilk package.status.updated gönderilir.
TRACKING_TIMEOUT (28) durumu için gönderilmez.
Gönderi seviyesindeki consignment.status.updated event'i eskisi gibi gönderilmeye devam eder. İki seviyeyi de almak için her event için ayrı webhook oluşturun.

Alan	Tip	Anlamı
`consignmentId`, `consignmentUuid`, `barcode`, `referenceNo`	integer, string	Paketin ait olduğu gönderi.
`packageId`	integer	Paketin ID'si.
`packageReferenceNo`, `providerPackageId`, `specificProviderBarcode`	string veya null	Paketin referans numarası, kargo firmasının pakete verdiği ID ve pakete özel kargo barkodu. Bilgi yoksa `null` gönderilir.
`providerPackageSequence`	integer veya null	Paketin kargo firmasındaki sıra numarası. Bilgi yoksa `null` gönderilir.
`status`, `statusMessage`	integer, string	Paketin güncel durumu. Durum değerleri Gönderi Durumları sayfasında listelenir.
`statusUpdatedAt`, `location`	tarih string'i, string veya null	Paketin son olayının tarihi ve konumu. Paketin henüz bir olayı yoksa `statusUpdatedAt` paketin son güncellenme zamanını taşır ve `location` `null` olur.
`weight`, `width`, `length`, `height`, `desi`	number veya null	Paketin kayıtlı ağırlığı (kg), ölçüleri (cm) ve desisi.
`events`	array	Yalnızca bu pakete ait olaylar, en eskiden yeniye.
`labels`	array	Yalnızca bu pakete ait label'lar (`trackingCode`, `trackingType`, `provider`, `providerId`).

{
  "headers": {
    "Authorization": "__YOUR_AUTH_KEY__",
    "Content-Type": "application/json"
  },
  "body": {
    "event": "package.status.updated",
    "data": {
      "consignmentId": 3393215,
      "consignmentUuid": "8f5ad2c9-3a2a-4e7d-a858-d1b9e17fd15d",
      "barcode": "C2H11294525102",
      "referenceNo": "EPTT898824753",
      "packageId": 42,
      "packageReferenceNo": null,
      "providerPackageId": null,
      "providerPackageSequence": null,
      "specificProviderBarcode": null,
      "status": 3,
      "statusMessage": "Sevk Edildi",
      "statusUpdatedAt": "2026-10-13T16:19:12+03:00",
      "location": "Istanbul/Kadikoy",
      "weight": 1.2,
      "width": 0,
      "length": 0,
      "height": 0,
      "desi": 2,
      "events": [
        {
          "status": 2,
          "statusMessage": "Kabul Edildi",
          "statusUpdatedAt": "2026-10-13T16:18:20+03:00",
          "location": "Istanbul/Kadikoy"
        },
        {
          "status": 3,
          "statusMessage": "Sevk Edildi",
          "statusUpdatedAt": "2026-10-13T16:19:12+03:00",
          "location": "Istanbul/Kadikoy"
        }
      ],
      "labels": [
        {
          "trackingCode": "KP17918974919TR",
          "trackingType": 1,
          "provider": "Ptt",
          "providerId": 1
        }
      ]
    }
  }
}

package.size.updated

Bir paketin ağırlığı, desisi, genişliği, uzunluğu veya yüksekliği değiştiğinde tetiklenir. Payload, package.status.updated ile aynı alanları taşır ve yeni ölçüleri içerir.

Webhook yalnızca gerçek değişikliklerde gönderilir. Yalnızca biçim farkı olan değerler (örneğin 9.0 ve 9.00) webhook göndermez.
Paket oluşturulması bu event'i tetiklemez. Yeni paketin ölçüleri, ilk package.status.updated içinde gönderilir.
Değişiklik gönderinin toplamlarını da değiştirirse, yeni toplamlarla consignment.size.updated gönderilir. Bu kural taslak gönderiler için geçerli değildir: taslak bir gönderinin paketleri güncellendiğinde package.size.updated gönderilebilir, ancak consignment.size.updated gönderilmez.
Paket henüz bir durum almadıysa status ve statusMessage null olabilir.

{
  "headers": {
    "Authorization": "__YOUR_AUTH_KEY__",
    "Content-Type": "application/json"
  },
  "body": {
    "event": "package.size.updated",
    "data": {
      "consignmentId": 3393215,
      "consignmentUuid": "8f5ad2c9-3a2a-4e7d-a858-d1b9e17fd15d",
      "barcode": "C2H11294525102",
      "referenceNo": "EPTT898824753",
      "packageId": 41,
      "packageReferenceNo": null,
      "providerPackageId": null,
      "providerPackageSequence": null,
      "specificProviderBarcode": null,
      "status": 2,
      "statusMessage": "Kabul Edildi",
      "statusUpdatedAt": "2026-10-13T16:18:04+03:00",
      "location": "Istanbul/Kadikoy",
      "weight": 2.5,
      "width": 10,
      "length": 15,
      "height": 15,
      "desi": 3,
      "events": [
        {
          "status": 2,
          "statusMessage": "Kabul Edildi",
          "statusUpdatedAt": "2026-10-13T16:18:04+03:00",
          "location": "Istanbul/Kadikoy"
        }
      ],
      "labels": [
        {
          "trackingCode": "8200000000211",
          "trackingType": 1,
          "provider": "Ptt",
          "providerId": 1
        }
      ]
    }
  }
}