Cron ile Webhook Tetikleme: POST, Header ve JSON

Cron ile webhook tetikleme, belirli saatlerde bir uygulamanın HTTP uç noktasına istek göndererek işlem başlatmaktır. Tarayıcıda açılan bir adresin çalışması, aynı adresin zamanlayıcıdan doğru çağrılacağı anlamına gelmez: sunucu POST bekleyebilir, JSON gövdesi isteyebilir veya kimlik doğrulaması yapabilir. Önce isteğin sözleşmesini, ardından zamanlamasını kurmanız gerekir.

Bu rehber, stok eşitleme veya rapor hazırlama gibi bir işi HTTP üzerinden başlatmak isteyen geliştiriciler içindir. Örneklerdeki example.com adresini kendi HTTPS adresinizle değiştirin. Komutları önce test ortamında deneyin; üretim üzerinde gönderilen başarılı bir istek gerçek veri değişikliğine yol açabilir. Genel zamanlama kavramları için cron job nedir rehberinden başlayabilirsiniz.

Webhook zamanlama senaryoları

Webhook genellikle başka bir sistemdeki olayın sizin uygulamanıza bildirilmesini anlatır. Burada çağrıyı olay yerine saat başlatır; alıcı açısından bu yine doğrulanması gereken bir HTTP isteğidir. Elinizde yalnızca bir yönetim ekranı varsa, o ekranın adresini zamanlamak yerine uygulamanızda bu amaçla bir API uç noktası tanımlayın.

Birinci senaryo, her on beş dakikada depodaki stokları mağazaya aktarmaktır. İstek gövdesi depo kodunu taşır; uygulama son başarılı eşitlemeden sonraki değişiklikleri işler. Bu aralık, her ürün için ayrı istek göndermek yerine değişiklikleri toplamanıza yardım eder. Aynı dönem yeniden işlendiğinde stok miktarlarını iki kez artırmamak için mutlak miktarları güncelleyin veya işlenen kayıtları takip edin.

İkinci senaryo, her iş günü saat 08.20'de önceki günün satış raporunu hazırlatmaktır. HTTP çağrısı raporu kuyruğa ekler; rapor dosyasının oluşmasını ayrı iş kaydı üzerinden izlersiniz. Raporun tamamlanması birkaç dakika sürüyorsa bağlantıyı açık tutmak yerine işlem kimliği döndürmek, ağ kesintisinde hangi raporun başlatıldığını anlamanızı kolaylaştırır.

Zamanlanmış çağrının hedefi yalnızca kendi uygulamanız olmak zorunda değildir. Düzenli veri toplama tarafındaki robots.txt ve hız limiti kuralları için cron ile web scraping rehberine, çağrının e-posta gönderme veya tablo güncelleme gibi zincir adımlar tetiklemesi gerektiğinde n8n zamanlanmış görev akışlarına bakabilirsiniz.

GET ve POST seçimi

Alıcı API'nin belgelerinde belirtilen metodu kullanın. GET çoğunlukla veri okumak içindir; işlem başlatan uç noktayı POST olarak tasarlamak daha anlaşılırdır. POST seçmek tek başına güvenlik sağlamaz. Kimlik doğrulama, yetki kontrolü ve yinelenen istekleri ele alma yine uygulamanın sorumluluğundadır. Üçüncü taraf sistemin sadece GET desteklediği durumda sözleşmeyi değiştirmeye çalışmayın.

Tarayıcı oturum çerezine bağlı bir adres, zamanlayıcıdan çağrıldığında giriş sayfasına yönlenebilir. Bu durumda giriş sayfasının 200 dönmesi işin yapıldığı anlamına gelmez. Kullanıcı oturumundan bağımsız, yalnızca gerekli işlemi yapmaya yetkili bir servis uç noktası hazırlayın.

JSON body hazırlama: adım adım ilk istek

1. Alıcının zorunlu alanlarını belirleyin. Örnekte işlem adı ve depo kodu kullanılıyor; bunlar örnek sözleşmeye aittir, her API tarafından kabul edilmez.
2. Sunucuda yalnızca sizin okuyabildiğiniz bir dizinde aşağıdaki JSON'u /opt/automation/sync.json dosyasına kaydedin. JSON'da alan adları ve metinler çift tırnakla yazılır; son alandan sonra virgül bırakılmaz.
3. Gerçek token'ı kaynak koduna eklemeden test kabuğunun WEBHOOK_TOKEN ortam değişkenine tanımlayın. Sonra aşağıdaki curl komutunu çalıştırın. Bu Bash örneğidir; Windows PowerShell üzerinde tırnak ve ortam değişkeni sözdizimi farklıdır.
4. Yanıt kodunu, yanıt gövdesini ve alıcıdaki iş kaydını birlikte inceleyin. Gerekli değişiklikleri test ortamında tamamlamadan periyodik çalışmayı açmayın.

{"task":"stock-sync","warehouse":"merkez"}

curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 45 \
  --request POST 'https://example.com/api/jobs/sync' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $WEBHOOK_TOKEN" \
  --data-binary @/opt/automation/sync.json

Gövdeyi dosyadan göndermek, kabuk tırnaklarıyla JSON tırnaklarının karışmasını önler. --fail-with-body HTTP 400 ve üzerindeki yanıtları hata çıkışına dönüştürürken gövdeyi korur. Komutunuz bu seçeneği tanımıyorsa kurulu curl sürümünü kontrol edin; seçenek ayrıntıları resmî curl kılavuzunda bulunur. Bu komuttaki süreler örneğe aittir, panelin timeout ayarını değiştirmez.

Content-Type ve özel header ayarları

Header, isteğin gövdesi veya yetkilendirmesi hakkında bilgi taşıyan başlık alanıdır. Content-Type: application/json gövdenin JSON olarak yorumlanmasını ister; Accept: application/json ise istenen yanıt biçimini belirtir. Accept eklemek, yanlış biçimde hazırlanmış gövdeyi JSON'a dönüştürmez. API form verisi bekliyorsa JSON yerine belgelenen içerik türünü gönderin.

Panelde header alanını doldururken alan adı olarak Content-Type, değer olarak application/json girin; gövde alanına yalnız JSON metnini yapıştırın. Curl komutunun tamamını gövdeye koymayın. Uygulama ayrıca X-Webhook-Token gibi özel bir alan bekleyebilir. Alanın adı ve değeri alıcıyla aynı olmalıdır; rastgele header eklemek yetki sağlamaz.

Basic Auth ve Bearer token

Basic Auth kullanıcı adı ve parolayı HTTP kimlik doğrulama mekanizmasıyla taşır. Bearer token ise genellikle Authorization: Bearer ... başlığında gönderilir. Hangi yöntemin desteklendiğini alıcı belirler. Basic Auth bilgisini panelin ilgili alanına girin; Bearer kullanıyorsanız özel Authorization header'ı tanımlayın. Aynı başlıkta iki farklı kimlik doğrulama yöntemi üretmeyin.

Token'ı URL sorgusuna yazmak yerine header kullanın ve aktarımı HTTPS ile koruyun. Sunucu gelen token'ı kendi gizli değeriyle doğrulamalı; eksik veya yanlış değerde işlemi başlatmadan isteği reddetmelidir. Yalnız gerekli göreve yetki verin. Sızan bir token'ı yenilerken hem alıcıdaki hem zamanlayıcıdaki değeri değiştirip manuel kontrol yapın. Daha kapsamlı önlemler için cron job güvenliği rehberini inceleyebilirsiniz.

İlk isteği doğrulama ve sık hatalar

Testte önce geçerli token ile bir çağrı yapın, ardından yanlış token ile aynı işlemin reddedildiğini doğrulayın. Uygulama günlüğüne token'ın kendisini yazmadan istek zamanı, işlem kimliği ve sonuç kaydedin. İstemcide görülen sonuç ile sunucudaki sonuç uyuşmuyorsa aradaki yönlendirme ve ters vekil kayıtlarını inceleyin. Kabul edilen işin sonucunu ekibe anlık iletmek isterseniz cron ile Telegram bildirimi rehberindeki bot ve chat id ayarlarını uygulamanıza ekleyebilirsiniz.

• 401 Unauthorized veya 403 Forbidden: Token eksik, süresi dolmuş ya da yetkisi yetersiz olabilir. Başlığın alıcıya ulaştığını ve ilgili göreve izin verildiğini kontrol edin. Bu kodların kesin anlamı için alıcının hata gövdesini okuyun.
• 405 Method Not Allowed: Uç nokta seçilen metodu kabul etmiyordur. Tarayıcıda GET ile açılan adresi POST yapmak yerine API'nin doğru işlem adresini bulun.
• 400 Bad Request veya 415 Unsupported Media Type: JSON sözdizimi, zorunlu alan ya da içerik türü hatalı olabilir. Önce küçük, belgelenmiş bir gövdeyle deneyin; sonra alanları tek tek ekleyin.
• 429 Too Many Requests: Alıcının istek sınırına ulaşmış olabilirsiniz. Aralığı büyütün, varsa Retry-After başlığını inceleyin ve toplu işlem kullanın. Art arda manuel denemelerle sınırı zorlamayın.
• Sertifika veya bağlantı hatası: Alan adı, DNS, sertifika zinciri ve ağ erişimini kontrol edin. Sertifika doğrulamasını kapatmak yerine doğru sertifikayı kurun; HTTP yanıtı alınamayan durumda gövdeden teşhis beklemeyin.

Timeout ve yinelenen istekler

Timeout, istemcinin yanıt beklemeyi bırakmasıdır; sunucudaki işlemin geri alındığını göstermez. Bağlantı kesildikten sonra stok güncellemesi tamamlanmış olabilir. Sonucu kontrol etmeden tekrar POST göndermek çift işlem oluşturabilir. Başarısız çağrıların otomatik olarak tekrarlandığını varsaymayın; tekrar politikasını kendi sisteminizde açıkça belirleyin.

Aynı mantıksal dönem için aynı iş anahtarını üretip veritabanında benzersiz tutmak, yeniden gelen isteğin ikinci iş açmasını önleyebilir. Idempotency-Key başlığı ancak alıcı bu sözleşmeyi gerçekten uyguluyorsa anlam taşır. Sabit bir anahtarı bütün dönemlerde kullanmak sonraki geçerli işleri de engelleyebilir. Aynı anda çalışma riski varsa ayrıca kilit veya kuyruk kullanın; aralığı uzatmak tek başına çakışma güvencesi değildir. Uç noktanın genel erişilebilirliğini sürekli izlemek isterseniz cron uptime monitoring rehberindeki dışarıdan yoklama yaklaşımı bu işe tamamlayıcıdır.

cronjob.com.tr kurulumu ve yanıt takibi

1. Yeni işin URL alanına https://example.com/api/jobs/sync yazın. Dışarıdan erişilebilir HTTPS uç noktası kullanın; localhost ve özel ağ adreslerine istek gönderilmez.
2. POST metodunu seçin. Content-Type ve gizli Authorization header'ını ekleyin; gövdeye test ettiğiniz JSON'u girin. Basic Auth kullanıyorsanız ilgili kullanıcı adı ve parola alanlarını doldurun.
3. On beş dakikalık hazır aralık veya */15 * * * * ifadesi seçin. İşin saat dilimini kontrol edin; varsayılan Europe/Istanbul'dur. İfade alanlarını öğrenmek için cron ifadeleri rehberine bakın.
4. Manuel çalıştırın; çalışma kaydındaki durum kodu, süre ve yanıt gövdesini alıcıdaki iş kimliğiyle karşılaştırın. Sonra ilk planlı çağrının da aynı sonucu verdiğini kontrol edin.

En kısa aralık 60 saniyedir. Hazır aralıklarda yanıt bekleme süresi aralıktan beş saniye çıkarılarak hesaplanır; alt sınır 5, üst sınır 290 saniyedir. Bir dakikalık işte 55 saniye, iki dakikalık işte 115 saniye, beş dakika ve üzerinde 290 saniye beklenir. Cron ifadeli işlerde sınır 290 saniyedir.

Bağlantı hatası olmadan alınan HTTP 200–399 yanıtları başarılı sayılır; bu, raporun tamamlandığını kanıtlamaz. Çalışma kayıtları yedi gün saklanır ve yanıt gövdesinin ilk yaklaşık 64 KB'ını içerir. Ardışık hata eşiği varsayılan üçtür, 1–20 arasında ayarlanabilir. Eşik aşılınca erişim sorunu, düzelince kesinti süresiyle düzeldi e-postası gönderilir; aynı işin bildirimleri arasında en az 60 dakika bulunur.

Tetikleyicinin edge ağı üzerinde çalışmasını istediğiniz uçlar için Cloudflare Workers cron kurulumunu da değerlendirebilirsiniz; orada zamanlama wrangler.toml içindeki cron tetikleyicisiyle tanımlanır.

Sıkça Sorulan Sorular (SSS)

Cron ile JSON gönderebilir miyim?

Evet. POST isteğinde JSON gövdesini ve Content-Type: application/json başlığını birlikte gönderin; alıcının beklediği alan adlarını kullanın.

Webhook adresini tarayıcıda açmak yeterli bir test mi?

Hayır. Tarayıcıdaki GET isteği POST gövdesini ve özel yetkilendirme başlıklarını sınamaz; planlanan isteği aynı metot ve verilerle test edin.

Timeout sonrası isteği hemen tekrarlamalı mıyım?

Önce alıcıdaki iş kaydını kontrol edin. Timeout sırasında işlem tamamlanmış olabilir; yeniden göndermeden önce yinelenen işlemleri engelleyen bir mekanizma kullanın.

HTTP 202 yanıtı işlemin bittiğini gösterir mi?

Hayır. 202 kabul yanıtıdır; işin tamamlanmasını uygulamanın iş kaydı veya sonuç uç noktası üzerinden ayrıca doğrulayın.

İlgili Rehberler