İçeriğe geç
Sursa Developers

POST/v1/webhooks

Webhook oluşturma

create_webhook

URL https kullanmalı ve ana makinesi herkese açık adreslere çözümlenmelidir. Özel (RFC 1918), geri döngü (loopback), bağlantı yerel (link-local), bulut meta veri ağları ve diğer özel amaçlı ağlar hem kayıt sırasında hem de her bağlantıda reddedilir. İmzalama gizli değeri yanıtta bir kez gösterilir (secret); bundan sonra yalnızca yenilenebilir. Bir kuruluşun en fazla 20 webhook’u olabilir.

Abonelik, olay türlerini ve olay grubu maskelerini (card.*, *) listeler. Erişim, bir API anahtarındakiyle aynı şekilde ayarlanır: role, data_profile_id ve collection_ids. Rolün, veri profilinin ya da koleksiyonların erişemediği bir nesneyle ilgili olay teslim edilmez. tags, kart olaylarını bu etiketlerden herhangi birine sahip kartlarla sınırlar. payload: thin olayları data olmadan gönderir. Özel başlıklar (headers) ve giden yetkilendirme (auth) şifrelenmiş olarak saklanır; yanıtlar yalnızca başlık adlarını ve value_set ile auth_set bayraklarını içerir.

Kimlik doğrulama

API anahtarını Authorization başlığında gönderin: Authorization: Bearer <anahtar>.

Başlık parametreleri

  • Idempotency-Keystring

    Bir yazma işleminin güvenli yeniden denenmesi için idempotency anahtarı (aynı isteğin tekrarı işlemi ikinci kez çalıştırmaz): 1–255 yazdırılabilir ASCII karakteri; her mantıksal işlem için bir UUID v4 önerilir. 24 saat içinde aynı anahtarla yapılan yeniden deneme işlemi tekrar çalıştırmaz: kaydedilmiş yanıtı (durum, başlıklar ve gövde) Idempotency-Replayed: true başlığıyla döndürür. Aynı anahtar farklı bir yöntem, yol, Content-Type ya da gövdeyle kullanılırsa 409 api.idempotency_mismatch döner; ilk istek hâlâ çalışırken Retry-After: 1 ile birlikte 409 api.idempotency_in_progress döner. 5xx ya da 429 yanıtından sonra anahtar serbest bırakılır ve yeniden deneme işlemi tekrar çalıştırır. Anahtar kuruluşa ve çağırana özgüdür (API anahtarı, kullanıcı ya da özel kaynak anahtarı).

    length ≥ 1, length ≤ 255

İstek gövdesi

application/json

Nesne: WebhookCreate

  • urlstringzorunlu

    Alıcı URL’si, yalnızca https://, en fazla 2048 karakter.

    length ≤ 2048

  • descriptionstring

    length ≤ 200

  • eventsarray of WebhookEventFilterzorunlu

    items ≥ 1

  • roleWebhookRole
  • data_profile_idinteger | null
  • collection_idsarray of integer

    Webhook’un hakkında olay aldığı koleksiyonlar. Değerin olmaması ya da boş liste, rolün ve veri profilinin erişebildiği tüm koleksiyonlar anlamına gelir. Kendisi koleksiyonlarla sınırlı olan bir anahtar, yalnızca kendi koleksiyonlarından oluşan boş olmayan bir listeyle webhook oluşturur. Bu alan olmadan, boş bir listeyle ya da onun listesi dışındaki bir koleksiyonla istek 403 webhooks.collections_outside_key döndürür.

    items ≤ 200

  • tagsarray of string

    items ≤ 50

  • payloadWebhookPayloadMode
  • headersarray of WebhookHeaderInput

    items ≤ 10

  • authWebhookAuthInput

Yanıtlar

201Oluşturuldu. `secret` yalnızca bu kez gösterilir.

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

  • Idempotency-Replayed

    true: yanıt bu Idempotency-Key için kaydedilmiş yanıttan yeniden verildi; işlem tekrar çalışmadı.

application/json

Nesne: WebhookCreated

  • idintegerzorunlu
  • urlstringzorunlu
  • descriptionstringzorunlu
  • eventsarray of WebhookEventFilterzorunlu
  • activebooleanzorunlu
  • statusWebhookStatuszorunlu
  • paused_atstring (date-time) | null
  • paused_reasonstring | null

    failures: art arda 10 başarısız deneme; feature_disabled: plan webhook’ları içermiyor.

  • disabled_reasonstring | null

    gone: alıcı 410 ile yanıt verdi; manual: bir yönetici tarafından devre dışı bırakıldı.

    Geçerli değerler: gonemanualnull

  • disabled_atstring (date-time) | null
  • roleWebhookRolezorunlu
  • data_profile_idinteger | null

    Webhook’un veri profili (null, aynı role sahip bir API anahtarındaki gibi profil olmadığı anlamına gelir).

  • collection_idsarray of integerzorunlu

    Webhook’un hakkında olay aldığı koleksiyonlar; boş liste, rolün ve veri profilinin erişebildiği tüm koleksiyonlar anlamına gelir.

  • tagsarray of stringzorunlu

    Kart olayları yalnızca bu etiketlerden herhangi birine sahip kartlar için; boş liste, filtre olmadığı anlamına gelir.

  • payloadWebhookPayloadModezorunlu
  • headersarray of WebhookHeaderzorunlu
  • auth_typestring | null

    Giden yetkilendirmenin türü (null, yetkilendirme olmadığı anlamına gelir).

    Geçerli değerler: bearerbasicnull

  • auth_setbooleanzorunlu

    Giden yetkilendirmenin ayarlanıp ayarlanmadığı (değerler hiçbir zaman döndürülmez).

  • previous_secret_valid_untilstring (date-time) | null

    Teslimlerin ne zamana kadar önceki gizli değerle de imzalanacağı (null, örtüşme süresi olmadığı anlamına gelir).

  • healthWebhookHealth
  • consecutive_failuresintegerzorunlu
  • last_delivery_atstring (date-time) | null
  • last_success_atstring (date-time) | null
  • last_errorstring | null
  • created_byinteger | null
  • created_by_namestring | null
  • created_atstring (date-time)zorunlu
  • updated_atstring (date-time)zorunlu
  • secretstringzorunlu

    whsec_ ve ardından base64 biçiminde 32 bayt (yeni gizli değerler dolgulu standart alfabeyi, eskiler base64url kullanır). Değeri alıcı tarafında saklayın; API yanıtlarında bir daha hiçbir zaman görünmez. Standard Webhooks imzalama anahtarı, whsec_ sonrasındaki kısmın base64 çözümlemesidir.

  • previous_valid_untilstring (date-time) | null

    Önceki gizli değerin ne zamana kadar kabul edileceği (yenilemeden sonra). Oluşturmada null.

400İstek geçersiz: bir parametre değeri ya da nesnenin durumu işleme izin vermiyor (`detail` bir iletidir).

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

401Kimlik bilgisi gönderilmedi (ne oturum çerezi ne de API anahtarı) ya da anahtar bulunamadı.

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

403İşleme izin verilmiyor: rol yetersiz, koleksiyona ya da karta erişim yok, istek “View as” modunda çalışıyor ya da kuruluş askıya alınmış veya silinmiş (`detail`, `code: org_suspended | org_deleted` içeren bir nesnedir).

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

409Nesnenin durumu işleme izin vermiyor; örneğin yinelenen bir kayıt, süren bir dizinleme ya da zaten işlenmiş bir iş.

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

422Geçerlilik hatası: gövde ya da parametreler şemaya uymuyor (`detail` geçerlilik hatalarının listesidir) ya da bir parametre değeri aralığın dışında (`detail` bir iletidir).

Yanıt başlıkları

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

429Çok fazla istek (`api.rate_limited`), kuruluşun dakika, gün ya da ay kotası doldu (`api.quota_exceeded`; `error.details` alanında `quota`, `limit` ve `reset_at` bulunur), kuruluşun limitine ulaşıldı ya da yanıt hizmeti meşgul (`answers.engine_busy`). `Retry-After` başlığındaki süre kadar bekleyin.

Yanıt başlıkları

  • Retry-After

    İsteği yeniden denemeden önce beklenmesi gereken saniye sayısı.

  • RateLimit-Policy

    Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.

  • RateLimit

    RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).

  • X-RateLimit-Remaining

    En sıkı limitte kalan istek sayısı.

  • X-RateLimit-Reset

    En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

Hata kodları

Bu uç noktanın, her isteğin genel kodlarının yanı sıra error.code alanında döndürebileceği kodlar.

Güvenli yeniden denemeler

Her POST ve PATCH isteğiyle bir Idempotency-Key başlığı (örneğin bir UUID) gönderin. Aynı anahtarla 24 saat içinde yapılan yeniden deneme, isteği yeniden çalıştırmak yerine kaydedilmiş yanıtı döndürür.

Hız sınırları

Yanıtlarda RateLimit ve RateLimit-Policy başlıklarıyla birlikte daha eski X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları bulunur. 429 yanıtında saniye cinsinden Retry-After başlığı vardır: bekleyin ve yeniden deneyin.

← webhooks · API başvurusu