Webhook'lar

Webhook, membership'te belirli bir olay gerçekleştiğinde seçtiğiniz bir URL'ye HTTP isteği gönderir. Diğer sistemleri ErtisAuth ile senkron tutmak için webhook'ları kullanın: bir kullanıcı kaydolduğunda bir müşteri kaydı oluşturun, bir kullanıcı silindiğinde verilerini temizleyin, bir rol değiştiğinde bir sohbet kanalına mesaj gönderin.

Webhook nesnesi#

{
	"_id": "66f1c0d2a4b5c6d7e8f901a0",
	"name": "Sync new users to CRM",
	"slug": "sync-new-users-to-crm",
	"description": "Creates a contact for every new user",
	"event": "UserCreated",
	"status": "active",
	"try_count": 3,
	"request": {
		"method": "POST",
		"url": "https://crm.example.com/hooks/ertisauth/users/{{document._id}}",
		"headers": {
			"Authorization": "Bearer <crm_api_key>",
			"X-Source": "ertisauth"
		},
		"body": {
			"email": "{{document.email_address}}",
			"name": "{{document.firstname}} {{document.lastname}}",
			"source": "signup"
		},
		"uncoveredBody": false
	},
	"membership_id": "66f1c0d2a4b5c6d7e8f90123"
}

Placeholder'lar#

URL, header değerleri ve gövdenin string değerleri, olaydan doldurulan çift süslü parantezli placeholder'lar içerebilir:

İç içe alanlar nokta kullanır: {{document.sys.created_by}}.

Değerler kullanıldıkları yere göre escape edilir; böylece bir olayın verisi (örneğin bir kullanıcının adı) isteği değiştiremez:

• URL'de değerler URL-encode edilir (../admin, ..%2Fadmin olur);
• header'larda satır sonu içerecek bir değer gönderilmez;
• gövde'de her placeholder kendi JSON string'inin içinde kalır: alan ekleyemez ya da yapıyı değiştiremez.

İstek gövdesi#

Varsayılan olarak (uncoveredBody: false) istek gövdesi, body'nizi olayın dokümanlarıyla birlikte sarmalar:

{
	"document": { "_id": "66f1c0d2a4b5c6d7e8f90127", "username": "ada", "email_address": "ada@example.com", "…": "…" },
	"prior": null,
	"payload": {
		"email": "ada@example.com",
		"name": "Ada Lovelace",
		"source": "signup"
	}
}

uncoveredBody: true ile istek gövdesi, placeholder'lar doldurulduktan sonra yalnızca sizin body'nizdir:

{
	"email": "ada@example.com",
	"name": "Ada Lovelace",
	"source": "signup"
}

Alıcı API belirli bir biçim bekliyorsa uncoveredBody: true kullanın.

Gönderim#

• Webhook'lar bir arka plan kuyruğundan asenkron olarak çağrılır: olaya yol açan istek onları beklemez ve yavaş ya da hata veren bir alıcı ErtisAuth'u yavaşlatamaz ya da bozamaz.
• Alıcı 2xx durum koduyla yanıt verdiğinde çağrı başarılı sayılır. Aksi halde, toplamda try_count kadar olmak üzere, art arda yeniden denenir.
• Her deneme, ne olduğunu görebilmeniz için istek, durum kodu ve yanıt gövdesiyle bir WebhookRequestSent ya da WebhookRequestFailed olayı kaydeder.
• Webhook'lar tam olarak bir kez değil, deneme başına en fazla bir kez gönderilir: alıcınızı idempotent yapın (örneğin document._id kullanarak) ve çağrı kuyruktayken ErtisAuth yeniden başlarsa kaçırılabileceğini göz önünde bulundurun.

Alıcınızı güvenli hale getirme#

• HTTPS kullanın.
• Çağrıları doğrulayın: bir header'a ("Authorization": "Bearer <secret>") ya da URL'ye bir secret koyun ve alıcınızda kontrol edin.
• Gövdeye körü körüne güvenmeyin: şüphe duyduğunuzda kaynağı bir uygulama token'ıyla ErtisAuth'tan okuyun.

Endpoint'ler#

Tüm route'lar /memberships/{membershipId} altındadır.

Webhook oluşturma#

curl -X POST https://auth.example.com/memberships/<membership_id>/webhooks \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '{
		"name": "Notify on user deletion",
		"event": "UserDeleted",
		"status": "active",
		"try_count": 3,
		"request": {
			"method": "DELETE",
			"url": "https://shop.example.com/api/customers/{{prior._id}}",
			"headers": { "Authorization": "Bearer <shop_api_key>" }
		}
	}'

Yanıt 201 Created: webhook.

Güncelleme ve silme#

PUT /webhooks/{id} webhook'u gövdeyle (oluşturmayla aynı alanlar) tamamen değiştirir. Hiçbir değişiklik içermeyen bir güncelleme 409 IdenticalDocumentError döner. DELETE /webhooks/{id} 204 No Content döner.

Olaylar#

WebhookCreated, WebhookUpdated, WebhookDeleted ve gönderim olayları WebhookRequestSent ile WebhookRequestFailed. Bkz. Olaylar.