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

# Webhook olayları ve veri paketleri

> OTO API ile bir webhook kaydedin, üç olay türünün her birinin ne gönderdiğini görün, HMAC-SHA256 imzalarını doğrulayın ve sağlam bir uç nokta kurun.

Webhook, entegrasyonun yönünü tersine çevirir. Birkaç dakikada bir OTO’ya ne olduğunu sormak yerine bir URL barındırırsınız ve OTO size haber verir.

## Üç olay türü

| Tür | Ne zaman tetiklenir? | Ne için kullanılır? |
| - | - | - |
| `orderStatus` | Bir siparişin durumu değiştiğinde: işleniyor, teslim edildi, iade edildi ve aradaki her şey. | Kendi sisteminizi ve müşterinizi güncel tutmak. Varsayılan tür budur. |
| `shipmentError` | Bir gönderi kargo şirketinde oluşturulamadığında. | Aksi hâlde yerinde sayacak siparişleri yakalamak. Kargo şirketinin kendi mesajını içerir. |
| `newOrders` | OTO’ya bir sipariş geldiğinde. | Siparişleri farklı bir WMS’e aktarmak. |

> [!TIP]
>
> **Başka hiçbir şeye abone olmasanız bile shipmentError’a abone olun**
>
> Başarısız bir rezervasyon doğası gereği sessizdir: Sipariş ilerlemez ve hiçbir şey değişmediği için durum değişikliği olayı da tetiklenmez.
>
> Yük (payload), nedeni belirtir: bir `errorCode` ve `deliveryCompanyResponse` alanında kargo şirketinin kendi ifadesi; genellikle eksik bir şehir ya da posta kodu gibi bir şey. Biri fark ederse bunlar saniyeler içinde düzeltilir; kimse fark etmezse günlerce görünmez kalır.

## Webhook kaydetme

`POST /rest/v2/webhook` Starter+

| Alan | Zorunlu | Ne işe yarar? |
| - | - | - |
| `url` | Evet | Sizin uç noktanız. |
| `method` | Evet | `POST` veya `PUT`. |
| `webhookType` | Hayır | Yukarıdaki üç türden biri. Varsayılan değerler `orderStatus` ve `newOrders`’dır. |
| `secretKey` | Hayır | Yük imzasının hesaplanmasında kullanılan ortak gizli anahtar. |
| `authorizationKey` | Hayır | Uç noktanızın diğer tüm istekleri reddedebilmesi için istekle birlikte gönderilen bir anahtar. |
| `timestampFormat` | Hayır | İstediğiniz zaman damgası biçimi, örn. `yyyy-MM-dd HH:mm:ss`. |
| `orderPrefix` | Hayır | OTO’nun sipariş kimliklerinde sisteminizin beklemediği bir önek varsa, göndermeden önce kaldırılacak önek. |

`GET` aboneliklerinizi listeler, `PUT` bir aboneliği `id` ile günceller, `DELETE` ise kaldırır. Hepsi aynı yol üzerindedir.

## Neler gelir?

Bir `orderStatus` yükü; siparişi ve yeni durumunu, varsa kargo şirketini ve sürücüyü, takip numarasını ve takip bağlantısını, kargo etiketi (AWB) bağlantısını ve **UTC** cinsinden bir `timestamp` değerini içerir.

Bir `shipmentError` yükü; `orderId`, bir `errorCode`, OTO’nun `errorMessage` değerini ve kargo şirketinin ham `deliveryCompanyResponse` yanıtını içerir.

Bir `newOrders` yükü siparişin tamamını içerir: adres, ürünler, ağırlık, tutarlar, ödeme yöntemi, satış kanalı ve depo.

## OTO’dan geldiğini doğrulama

Her yük bir `signature` içerir: Kaydettiğiniz `secretKey` ile, iki nokta üst üste ile birleştirilmiş bir dize üzerinden hesaplanan ve base64 ile kodlanan bir **HMAC-SHA256** değeri.

| Olay türü | İmzalanan dize |
| - | - |
| `orderStatus` | `orderId:status:timestamp` |
| `shipmentError` | `orderId:errorCode:timestamp` |

> [!WARNING]
>
> **İmzayı doğrulayın ve eski zaman damgalarını reddedin**
>
> Webhook URL’nize, onu öğrenen herkes erişebilir. Doğrulama yapmazsanız, bu kişilerden herhangi biri sisteminize bir siparişin teslim edildiğini söyleyebilir.
>
> İmzalanan dize üzerinden HMAC’i yeniden hesaplayın ve sabit süreli (constant-time) bir karşılaştırmayla kontrol edin. Ardından zaman damgasının yeni olduğunu doğrulayın: Eski bir yükteki geçerli imza bir tekrar saldırısıdır (replay) ve dünkü siparişi yeniden teslim edildi olarak işaretlemek, yol açabileceği en hafif sonuçtur.

## Sağlam bir uç nokta oluşturma

* **Hemen yanıt verin.** Yükü alır almaz 200 döndürün, işlemleri sonra yapın. Yavaş bir uç nokta, bozuk bir uç nokta gibi görünür.
* **Tekrarları bekleyin.** Gönderimler tekrarlanabilir. `orderId`, durum ve zaman damgasını anahtar olarak kullanın ve yeniden işlemeyi zararsız hâle getirin.
* **Sırasız gelmelerini bekleyin.** Ağ zamanlaması durum makinenize uymaz. Eski bir olay geç geldi diye bir siparişi asla geriye taşımayın.
* **Ham gövdeyi ayrıştırmadan önce kaydedin.** Bir entegrasyon gece saat 2’de sorun çıkardığında, ihtiyacınız olan yük tam da saklamadığınız yüktür.

## İlgili sayfalar

* [Kimlik Doğrulama](https://docs.tryoto.com/tr/developers/authentication.md) — belirteçler ve test ortamı.
* [Durum ve Takip Güncellemeleri](https://docs.tryoto.com/tr/modules/sales-channels/updates.md) — aynı olayların bir satış kanalına gönderilmesi.
* [Uç nokta dizini](https://docs.tryoto.com/tr/developers/rest-api-reference.md) — geri kalan her şey.


## Related topics

- [Gerçek zamanlı güncellemeler için webhook’lar](https://docs.tryoto.com/tr/integrations/webhooks.md)
- [Güvenlik ve uyumluluk](https://docs.tryoto.com/tr/platform/security-and-compliance.md)
- [Temel kavramlar: sipariş, gönderi, stok ve hub](https://docs.tryoto.com/tr/get-started/core-concepts.md)


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