راهنمای webhookهای نیواد
وب هوک(Webhook) چیست؟
وب‌هوک که به آن Web callback و HTTP push API هم گفته می‌شود، عملاً یک Call back است که هنگام اتفاق افتادن رویدادهایی از پیش تعیین شده فراخوانی می‌شود و از طریق HTTP اطلاعاتی را به URLای که از پیش تعریف شده ارسال می‌کند.
وب‌هوک‌های نیواد
در حال حاضر نیواد یک وب‌هوک برای اطلاع رسانی خریدهای درون برنامه‌ای موفق در اختیار شما قرار می‌دهد.
وب‌هوک خرید موفق
| کد وب‌هوک | billing.purchase | ||
|---|---|---|---|
| شرایط رخداد | پس از انجام یک خرید موفق در اپلیکیشن | ||
| متدهای پشتیبانی شده | GET, POST, PUT, DELETE | ||
| متد پیشنهادی | POST | ||
| هدرها (HTTP Headers) | X-Mac | HMAC بدنهٔ درخواست (Payload) با کلید فراهم شده در زمان تعریف وب‌هوک | |
| فرمت اطلاعات ارسالی | GET | Query String | |
| POST, PUT, DELETE | application/json | ||
| اطلاعات ارسال شده (Payload) | کلید | مقدار | مثال |
| app_package_name | اسم پکیج اپلیکیشن | io.nivad.testapp | |
| market_name | نام مارکت اندرویدی که خرید از آن انجام شده | cafe-bazaar | |
| product_id | شناسهٔ کالا (sku) | full_version | |
| purchase_id | شناسهٔ یکتای هر خرید | 01641929-a543-4eb0-a777-3cb92fcfed1e | |
| purchase_time | زمان انجام خرید (زمانی که در مارکت ثبت شده) به فرمت استاندارد ISO 8601 | 2016-11-04T19:32:03.973855 | |
| webhook_payload | رشتهٔ دلخواه شما که در اپلیکیشن با متد purchase یا subscribe می‌فرستید. پیشنهاد می‌کنیم که شناسه‌ای یکتا از کاربر یا دستگاه اندرویدی مورد نظر را برای track کردن خرید بفرستید. | {"device_id":"45a72d502d46"} | |
نمونهٔ فراخوانی:
POST /api/v1/webhooks/purchase
Host: www.example.com
Content-Type: application/json
User-Agent: NivadWebhook/1.0 (https://nivad.io/docs/webhooks/)
X-Mac: 5e44385b7661715e4529f19aedd90caa
{
"app_package_name": "io.nivad.testapp",
"market_name": "cafe-bazaar",
"product_id": "full_version",
"purchase_id": "96111718-c854-4a16-8f8a-482318f22402",
"purchase_time": "2016-11-04T19:42:03.973855",
"webhook_payload": "{\"device_id\":\"45a72d502d46\"}"
}در متدهای purchase و subscribe یک پارامتر اختیاری تعبیه شده که می‌توانید به آن یک رشته پاس بدهید و این مقدار در کلید webhook_payload به سرور شما پاس داده می‌شود. در این رشته هر عبارت دلخواهی که به کارتان می‌آید را می‌توانید قرار دهید، مثلا android id دستگاهی که خرید روی آن انجام شده.
اعتبار سنجی و صحت سنجی اطلاعات
زمانی که یک وب‌هوک در پنل مدیریت اپلیکیشن‌تان در نیواد تعریف می‌کنید، از شما کلید HMAC پرسیده می‌شود. تمام فراخوانی‌هایی که نیواد روی سرور شما انجام می‌دهد با این کلید امضا می‌شوند. به کمک این امضا، سرور دریافت کنندهٔ وب‌هوک می‌تواند هم صحت و دستکاری نشده بودن بدنهٔ پیام را چک کند و هم می‌تواند مطمئن شود که وب‌هوک از طرف سرور نیواد فراخوانی شده و نه جای دیگر.
برای اطلاعات بیشتر دربارهٔ HMAC می‌توانید به صفحهٔ ویکی‌پدیای HMAC مراجعه کنید. در زیر کد نمونه‌ای به زبان پایتون آمده که HMAC درخواست ورودی را محاسبه و تأیید می‌کند.
def check_mac(request_body, shared_secret, request_mac_header):
import hmac
mac_checker = hmac.new(shared_secret.encode('utf-8'))
mac_checker.update(request_body.encode('utf-8'))
return mac_checker.compare_digest(mac_checker.hexdigest(), request_mac_header)