با وبهوکها میتوانید رویدادهای مهم پلتفرم را بهصورت بلادرنگ در سامانه خود دریافت کنید.
مکانیزمی برای دریافت رویدادها بهصورت Push به جای Pull
وبهوک (Webhook) یک آدرس HTTP است که شما در اختیار نوباتایم قرار میدهید. هرگاه رویداد مشخصی (مثل ساخت نوبت یا ثبت نظر) در پلتفرم رخ دهد، نوباتایم یک درخواست POST حاوی اطلاعات رویداد را به آن آدرس ارسال میکند. این روش برعکس API که باید دائماً نظرسنجی کنید، بهینهتر و بلادرنگتر است.
فهرست رویدادهایی که میتوانید در وبهوک خود دریافت کنید
appointment.createdساخت نوبتزمانی که یک بیمار نوبت جدید رزرو میکند، قبل از پرداخت ارسال میشود.
فعالشده در: POST /api/appointments
{
"appointmentId": "cklmnopqrst123",
"doctorId": "ckabcd1234",
"doctorName": "دکتر سارا محمدی",
"userId": "ckuser1234",
"patientName": "علی رضایی",
"date": "2024-12-15",
"startTime": "10:00",
"endTime": "10:30",
"visitType": "in-person",
"feeToman": 200000,
"status": "pending"
}appointment.cancelledلغو نوبتزمانی که یک نوبت توسط بیمار، پزشک یا مدیر لغو میشود ارسال میشود.
فعالشده در: DELETE /api/appointments/[id]
{
"appointmentId": "cklmnopqrst123",
"doctorId": "ckabcd1234",
"userId": "ckuser1234",
"cancelledBy": "patient",
"reason": "تغییر برنامه",
"previousStatus": "confirmed",
"cancelledAt": "2024-12-10T08:30:00.000Z"
}appointment.completedتکمیل ویزیتزمانی که پزشک وضعیت نوبت را به «تکمیلشده» تغییر میدهد ارسال میشود.
فعالشده در: PUT /api/appointments/[id] (status=completed)
{
"appointmentId": "cklmnopqrst123",
"doctorId": "ckabcd1234",
"userId": "ckuser1234",
"completedAt": "2024-12-15T10:35:00.000Z",
"feeToman": 200000
}review.submittedثبت نظر جدیدزمانی که یک بیمار پس از ویزیت، نظر و امتیازی برای پزشک ثبت میکند.
فعالشده در: POST /api/reviews
{
"reviewId": "ckrev1234",
"doctorId": "ckabcd1234",
"userId": "ckuser1234",
"userName": "علی رضایی",
"rating": 5,
"comment": "بسیار دقیق و حرفهای",
"verifiedReview": true,
"submittedAt": "2024-12-15T11:00:00.000Z"
}doctor.approvedتأیید پزشکزمانی که مدیر سامانه، حساب یک پزشک جدید را تأیید میکند ارسال میشود.
فعالشده در: POST /api/admin/doctors (action=approve)
{
"doctorId": "ckabcd1234",
"doctorName": "دکتر سارا محمدی",
"specialty": "قلب و عروق",
"city": "تهران",
"medicalCouncilCode": "123456",
"approvedBy": "ckadmin1",
"approvedAt": "2024-12-10T12:00:00.000Z"
}هر وبهوک یک درخواست POST با بدنه JSON و هدرهای زیر است
| هدر | توضیح |
|---|---|
| Content-Type | application/json |
| X-Nobatime-Event | نام رویداد (مثلاً appointment.created) |
| X-Nobatime-Signature | امضای HMAC-SHA256 (در صورت تنظیم Secret) |
| X-Nobatime-Delivery | شناسه یکتای این ارسال (برای دیباگ) |
| User-Agent | nobatime-webhook/1.0 |
{
"event": "appointment.created",
"deliveredAt": "2024-12-15T10:00:00.000Z",
"data": {
"appointmentId": "cklmnopqrst123",
"doctorId": "ckabcd1234",
"doctorName": "دکتر سارا محمدی",
"userId": "ckuser1234",
"patientName": "علی رضایی",
"date": "2024-12-15",
"startTime": "10:00",
"endTime": "10:30",
"visitType": "in-person",
"feeToman": 200000,
"status": "pending"
}
}2xx (مثلاً 200 یا 204) پاسخ دهد. در غیر این صورت، ارسال ناموفق تلقی شده و تا ۳ بار تلاش مجدد میشود.برای جلوگیری از درخواستهای جعلی، امضای هر درخواست را تأیید کنید
اگر هنگام ثبت وبهوک یک secret تنظیم کرده باشید، نوباتایم با کلید شما بدنه درخواست را با الگوریتم HMAC-SHA256 امضا میکند و نتیجه را در هدر X-Nobatime-Signature (بهصورت هگزادسیمال) قرار میدهد. برای اطمینان از اصالت درخواست، مقدار این هدر را با امضای محاسبهشده در سرور خود مقایسه کنید.
curl -X POST https://your-server.com/webhook \
-H "Content-Type: application/json" \
-H "X-Nobatime-Event: appointment.created" \
-H "X-Nobatime-Signature: <hex-hmac>" \
-H "X-Nobatime-Delivery: <delivery-id>" \
-d '{"event":"appointment.created","data":{...}}'import crypto from "crypto";
app.post("/webhook", (req, res) => {
const sig = req.headers["x-nobatime-signature"];
const secret = process.env.NOBATIME_WEBHOOK_SECRET;
const body = JSON.stringify(req.body); // raw body
const expected = crypto
.createHmac("sha256", secret)
.update(body)
.digest("hex");
// Use timingSafeEqual to prevent timing attacks
const a = Buffer.from(sig);
const b = Buffer.from(expected);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
return res.status(401).send("invalid signature");
}
// Signature OK — process the event
const { event, data } = req.body;
console.log("Received:", event, data);
res.status(200).send("ok");
});<?php
$secret = getenv("NOBATIME_WEBHOOK_SECRET");
$body = file_get_contents("php://input");
$sig = $_SERVER["HTTP_X_NOBATIME_SIGNATURE"] ?? "";
$expected = hash_hmac("sha256", $body, $secret);
if (!hash_equals($expected, $sig)) {
http_response_code(401);
echo "invalid signature";
exit;
}
$payload = json_decode($body, true);
$event = $payload["event"];
$data = $payload["data"];
// Process the event
http_response_code(200);
echo "ok";timingSafeEqual (Node) یا hash_equals (PHP) برای مقایسه امضا استفاده کنید تا از حملات زمانسنجی جلوگیری شود.دو روش برای ثبت وبهوک وجود دارد
با ارسال درخواست POST به /api/webhooks با بدنه زیر (نیازمند کوکی نشست مدیر):
curl -X POST https://nobatime.ir/api/webhooks \
-H "Content-Type: application/json" \
-H "Cookie: nobatime_sessions=<admin-cookie>" \
-d '{
"action": "register",
"url": "https://your-server.com/webhook",
"events": ["appointment.created", "appointment.cancelled"],
"secret": "your-strong-secret",
"description": "Production webhook"
}'پس از ثبت، میتوانید یک رویداد آزمایشی ارسال کنید
از پنل مدیریت، در بخش فهرست وبهوکها، روی دکمه «ارسال تست» کلیک کنید. نوباتایم یک رویدادappointment.createdآزمایشی به URL شما ارسال میکند و نتیجه (کد وضعیت، پاسخ و تعداد تلاش) را در جدول «آخرین ارسالها» نمایش میدهد.
{
"event": "appointment.created",
"deliveredAt": "2024-12-15T10:00:00.000Z",
"data": {
"test": true,
"message": "این یک رویداد آزمایشی از نوباتایم است",
"webhookId": "ckwh_12345",
"url": "https://your-server.com/webhook",
"sentAt": "2024-12-15T10:00:00.000Z"
}
}