Webhook’lara genel bakış

Sursa her önemli değişiklik için bir olay kaydeder: bir kart yayımlanır, doğrulanır ya da arşivlenir, bir duyuru okunur, bir soru yanıtsız kalır. Olayları iki yoldan alabilir ve ikisini birlikte kullanabilirsiniz:

İkisi de aynı olayları aynı kimliklerle taşır. Her olay, ona abone olan bir webhook olsun ya da olmasın, beslemede 30 gün saklanır.

Olay

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "card.updated",
  "created_at": "2026-10-24T10:00:03Z",
  "org_id": 1,
  "api_version": "1.60.0",
  "sequence": 1042,
  "object": {"type": "card", "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"},
  "payload": "full",
  "data": {
    "card": {"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "collection": "support", "version": 4},
    "actor_id": 7,
    "previous_attributes": {"title": "Refunds"}
  },
  "test": false
}

data yalnızca nesnenin herhangi bir okurunun API üzerinden görebileceği bilgileri içerir. Hiçbir zaman erişim listeleri, başka kişilerin izinleri ya da gizlenen alanlar içermez. Olaylardaki nedenler no_hits, restricted ya da index_failed gibi kısa nötr kodlardır.

Olay türleri

Olaylar şu konuları kapsar:

Her olayın şemasını ve bir örneğini içeren tam liste, API başvurusunun olay kataloğunda yer alır. GET /v1/webhooks/catalog kurulumunuzda kullanılabilen türleri döndürür.

Zamanla yeni olay türleri eklenir ve mevcut olaylar yeni alanlar kazanır. Olay türleri hiçbir zaman yeniden adlandırılmaz ya da kaldırılmaz. Alıcınız bilmediği türleri ve alanları atlamalıdır.

Kim neyi alır

Bir webhook bir olayı yalnızca olayın nesnesine erişebiliyorsa alır; bu, bir API anahtarında olduğu gibi webhook’un rolüne, veri profiline ve koleksiyonlarına göre belirlenir. support koleksiyonuyla sınırlı bir webhook, finance koleksiyonundaki kartlarla ilgili olayları hiçbir zaman almaz. Kişiler, anahtarlar, kaynaklar, içe aktarmalar, işler, dışa aktarmalar, faturalandırma, uygulamalar ve webhook’ların kendileriyle ilgili olaylar yalnızca admin rolüne sahip webhook’lara gider.

Bu sınırlar içinde her webhook kendi olaylarını seçer:

• türe göre, maskelerle: tüm kart olayları için card.*, tüm olaylar için *;
• kart olaylarında koleksiyona ve etikete göre.

Bir webhook’un veri yükü modu full (data ile birlikte olay; varsayılan) ya da thin (data olmadan olay: alıcınız nesneyi kendi anahtarıyla API üzerinden okur ve her zaman güncel durumunu görür) olabilir.

Kısaca teslim

• Olayı JSON olarak içeren ve webhook’un gizli değeriyle iki biçimde imzalanmış bir HTTPS POST isteği: Standard Webhooks (webhook-signature) ve eski X-KB-Signature.
• 10 saniye içinde verilen her 2xx yanıtı başarı sayılır.
• Başarısız bir teslim, giderek uzayan aralarla yaklaşık üç gün boyunca yeniden denenir. 429 ya da 503 yanıtındaki Retry-After başlığına uyulur; 410 webhook’u devre dışı bırakır; art arda 10 başarısızlık webhook’u yeniden etkinleştirilene kadar duraklatır.
• Bir webhook’a yapılan teslimler kesin olarak sırayla gönderilir. Yavaş bir webhook diğer webhook’ları geciktirmez.
• Aynı olay birden fazla kez gelebilir: yinelenenleri webhook-id değerine göre ayıklayın.

Webhook’ları alma kılavuzu, Node.js, Python ve Go’da imza denetimleriyle eksiksiz bir alıcıyı adım adım anlatır.

Webhook’ları yönetme

Webhook’ları yönetmek için admin rolüne ve webhooks:manage kapsamına sahip bir anahtar ya da yönetim arayüzünde bir yönetici gerekir. Bir kuruluşun en fazla 20 webhook’u olabilir. Webhook’lar kuruluşun planının bir parçasıdır; plan bunları içermiyorsa bu uç noktalar webhooks.feature_disabled koduyla 403 yanıtı verir.