Web kancası ucu ekle

POST /v1/webhook-endpoints · izin webhook-endpoints:write · bütün planlar

Ortamın olaylarını Standard Webhooks v1 imzasıyla alan bir uç ekler. Teslim en az bir kezdir: yinelenenleri webhook-id başlığıyla ayıklayın.

İmza sırrı. Yanıt signing_secret (idp_whsec_…) alanını bir kez, Cache-Control: no-store ile taşır. Yeniden alınamaz; hemen saklayın. Aynı Idempotency-Key ile tekrarlanan istek ucu sırsız ve secret_redacted: true ile döndürür. Sır kaybolur ya da sızarsa imza sırrını yenileyin.
URL. Yalnız https, port yok ya da 443, kullanıcı bilgisi ve parça yok, IP değişmezi yok, en çok 2.048 karakter. Yönlendirme izlenmez.
Olaylar. event_types katalog olay türlerini listeler; boş liste yüksek hacimli türler dışındaki bütün türler demektir.
Sınır. Bir ortamda en çok Free 3, Startup 20, Business 20 ya da Enterprise 50 etkin uç olabilir.

İstek

Alan	Tür	Zorunlu	Açıklama
`url`	string	evet	Alıcı adresi (kurallar yukarıda).
`key`	string	hayır	Ortamda tekil kararlı anahtar: `[a-z0-9][a-z0-9_-]{0,63}`. Varsayılan `endpoint-<kimliğin son 8 karakteri>`.
`description`	string	hayır	En çok 500 karakter.
`event_types`	array	hayır	Katalog olay türleri, en çok 100, yinelenmez. Boş ya da yok: yüksek hacimli türler dışındaki bütün türler.
`event_schema_versions`	object	hayır	Olay türü → şema sürümü. Listelenmeyen tür en eski desteklenen sürümüyle gönderilir.
`payload_mode`	string	hayır	`thin` (varsayılan: kimlikler, değişen alan adları ve durum alanları, kişisel veri yok) ya da `full` (kaynağın yönetim API'si temsili).
`rate_limit_per_second`	integer	hayır	Bu uca saniyede 1–1.000 teslim; varsayılan 50.
`status`	string	hayır	`enabled` (varsayılan) ya da `disabled_by_user`.
`Idempotency-Key`	başlık	hayır	Aynı anahtarla tekrarlanan istekte yanıtı (sırsız) yeniden oynatır.

{
  "url": "https://hooks.example.com/keenauth",
  "key": "crm-sync",
  "description": "CRM sync",
  "event_types": ["user.created", "user.updated"]
}

Yanıt

201 Created: uç, sürümünü taşıyan ETag ve sır. Diğer alanlar Web kancası ucunu getir sayfasındadır.

{
  "id": "whe_01k8a3m5q7t9v1w3x5y7z9b2c4",
  "key": "crm-sync",
  "url": "https://hooks.example.com/keenauth",
  "description": "CRM sync",
  "event_types": ["user.created", "user.updated"],
  "event_schema_versions": {},
  "payload_mode": "thin",
  "status": "enabled",
  "rate_limit_per_second": 50,
  "previous_secret_expires_at": null,
  "last_success_at": null,
  "failing_since": null,
  "version": 1,
  "created_at": "2026-10-26T09:00:00Z",
  "updated_at": "2026-10-26T09:00:00Z",
  "signing_secret": "idp_whsec_<secret>"
}

Hatalar

HTTP	code	Ne zaman
400	`unknown_field`	Gövdede yukarıda olmayan bir alan var.
403	`quota_exceeded`	Ortamda planın etkin uç sayısı dolu ya da ortamın planı bilinmiyor.
409	`conflict`	Ortamın başka bir ucu bu `key`'i kullanıyor.
422	`validation_failed`	`/url required`, `/url invalid_webhook_url`, `/key invalid`, `/description too_long`, `/event_types unknown_event_type`, `/event_types duplicate`, `/event_types too_many`, `/event_schema_versions unsupported_schema_version`, `/payload_mode invalid`, `/rate_limit_per_second out_of_range`, `/status invalid`.
422	`idempotency_key_reuse`	`Idempotency-Key` farklı bir istekle kullanılmış.
401	`unauthenticated`	Kimlik bilgisi yok, geçersiz ya da iptal edilmiş.
403	`insufficient_permissions`	Kimlik bilgisinde `webhook-endpoints:write` yok.
429	`rate_limited`	Hız sınırı aşıldı; `Retry-After` süresinden sonra yeniden deneyin.
503	`service_unavailable`	Web kancası yönetimi geçici olarak kullanılamıyor; `Retry-After` süresinden sonra yeniden deneyin.

Örnek

curl -X POST https://api.eu.keenauth.com/v1/webhook-endpoints \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f" \
  -d '{"url":"https://hooks.example.com/keenauth","key":"crm-sync","event_types":["user.created","user.updated"]}'

CLI: keenauth webhook-endpoints create --url https://hooks.example.com/keenauth --key crm-sync --event-types user.created,user.updated