Webhook'lar

Entegrasyonun okuyabildiği bir iş emrine ya da geri bildirime bir şey olunca kommuns, entegrasyonun webhook adreslerine imzalı bir POST gönderir; sisteminiz sormadan haberdar olur.

Kurulum

Organizasyon › Entegrasyonlar'da entegrasyonun Webhook'lar penceresi: Yeni webhook, adresi (https://, internetten erişilebilir) ve alacağı olay türleri. Bir kez gösterilen imza sırrını kopyalayın. Test gönder bir ping gönderip yanıtı gösterir; her adresin teslimleri Yeniden gönder ile listelenir. Bir entegrasyonun en çok 5 adresi olabilir.

Olaylar

Tür	Ne zaman	data'daki ek alanlar
work_order.created	İş emri oluşturuldu
work_order.updated	Başlık, açıklama, öncelik ya da hedef tarih değişti	fields
work_order.status_changed	Her durum değişikliği	previous_status, status
work_order.completed	Tamamlandı	previous_status, status
work_order.sent_to_inspection	Tamamlandı, danışmanı bekliyor	previous_status, status
work_order.cancelled	İptal edildi	previous_status, status
work_order.assignees_changed	Yetkililer eklendi / çıkarıldı	added, removed
issue.created	Geri bildirim açıldı
issue.resolved	Geri bildirim çözüldü
ping	Test gönder	message

Bir tamamlanma hem work_order.status_changed hem work_order.completed gönderir — ihtiyacınız olanlara abone olun. Bir adres bir olayı yalnız entegrasyon o iş emrini ya da geri bildirimi okuyabiliyorsa alır (kapsamlar ve yetkiler).

İstek

POST /your/webhook
Content-Type: application/json
Kommuns-Event-Id: 3f0c…
Kommuns-Event-Type: work_order.completed
Kommuns-Signature: t=1760000000,v1=5d41402abc4b2a76b9719d911017c592…

{"id": "3f0c…", "type": "work_order.completed", "created_at": "2026-10-05T12:00:00Z",
 "organization_id": "…",
 "data": {"work_order": {"id": "…", "title": "…", "status": {"code": "complete", "name": "Completed"}, "…": "…"},
          "previous_status": "in_progress", "status": "complete", "actor": {"identity_id": "…"}}}

data.work_order / data.issue, kayıt olay teslim edildiğinde GET /work-orders/{id} / GET /issues/{id}'nin gösterdiği hâliyledir (adlar İngilizce). data.actor değişikliği yapandır (identity_id; çözülen geri bildirimde user_id) — kendi değişikliklerinizi atlamak için GET /me'deki entegrasyonun identity_id'siyle karşılaştırın.

10 saniye içinde 2xx yanıt verin; işi sonra yapın (bir kuyrukla). Yönlendirmeler izlenmez.

İmzayı doğrulamak

Kommuns-Signature: t=<unix zaman>,v1=<hex HMAC-SHA256(sır, "<t>.<ham gövde>")>. İmzayı ham gövde üzerinden (JSON'u çözmeden önce) hesaplayın, sabit zamanlı karşılaştırın ve 5 dakikadan eski zamanı reddedin.

Python

import hashlib
import hmac
import time

def verified(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    timestamp, signature = int(parts["t"]), parts["v1"]
    if abs(time.time() - timestamp) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Node.js

import crypto from 'node:crypto';

export function verified(secret, header, rawBody, tolerance = 300) {
  const parts = Object.fromEntries(header.split(',').map((item) => item.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > tolerance) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.`).update(rawBody).digest('hex');
  return expected.length === parts.v1.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Teslim

• En az bir kez: aynı olay (Kommuns-Event-Id) iki kez gelebilir — işlediğiniz kimlikleri saklayın.
• Sıra: genellikle değişikliklerin sırasıyla, ama garanti değil; changed_at'i ya da kaydın kendisini kullanın.
• Yeniden deneme: başarısız bir teslim (2xx değil, zaman aşımı) 1 ve 5 dakika, 30 dakika, 2, 6, 12 ve 24 saat sonra yeniden denenir (yaklaşık iki günde 8 deneme); sonra başarısız sayılır. Teslim listesinden Yeniden gönder ile gönderebilirsiniz.
• Kapatma: bir teslim kesin başarısız olduğunda adresin 3 gündür hiç başarılı teslimi yoksa adres kapatılır; sayfa nedenini gösterir. Alıcıyı düzeltin, adresi yeniden açın ve yeniden gönderin.
• Olaylar 30 gün saklanır. Kaçırdıklarınız için changed_since ile eşitleyin.