Webhook listener در Postman به شما یک URL عمومی می‌دهد تا آن را در سرویس‌دهنده‌هایی مثل ابزارهای پرداخت، CI/CD، CRM یا هر provider دیگری ثبت کنید. بعد از آن، رویدادهای ورودی webhook داخل Postman ذخیره می‌شوند و می‌توانید آن‌ها را بررسی، route یا دوباره اجرا کنید.
این قابلیت برای پلن‌های Postman Solo، Team و Enterprise در دسترس است. هر webhook از یک IP حداکثر ۱۰۰ درخواست در دقیقه می‌پذیرد.
Webhook listener چه کاری انجام می‌دهد؟
- هر event ورودی را با header خام، body خام، زمان دریافت و status پاسخ ثبت می‌کند.
- می‌تواند event را به یک URL دیگر forward کند.
- می‌تواند مستقیم به producer پاسخ سفارشی بدهد.
- می‌تواند eventهای ثبت‌شده را replay کند تا بدون درخواست دوباره از provider، handler خود را تست کنید.
ساخت listener
- در sidebar روی گزینه افزودن کلیک کنید و Webhook را انتخاب کنید.
- در بالای workbench روی Webhook URL کلیک کنید و URL را برای provider خود کپی کنید.
listener از همان لحظه شروع به دریافت event می‌کند. هر listener یک URL پایدار دارد و با خاموش و روشن کردن listener تغییر نمی‌کند:
https://<webhook-id>.webhook.pstmn.ioبررسی eventهای دریافت‌شده
همه eventها در تب Events ذخیره می‌شوند. برای هر event می‌توانید header خام، body خام، زمان دریافت و status پاسخ را ببینید. Postman بدنه event را تغییر قالب نمی‌دهد و آن را همان‌طور که رسیده نمایش می‌دهد.
Routing eventها
در تب Routing مشخص می‌کنید Postman با event ورودی چه کار کند. دو حالت اصلی وجود دارد: forward کردن event به یک URL دیگر، یا پاسخ دادن مستقیم به producer. این دو حالت هم‌زمان فعال نمی‌شوند.
Forward کردن
در حالت Forward، هر event به URL هدف فرستاده می‌شود. این URL می‌تواند آدرس public، محیط staging یا حتی localhost شما باشد؛ بنابراین هنگام توسعه محلی همیشه لازم نیست ابزار tunnel جداگانه راه‌اندازی کنید.
- تب Routing را باز کنید.
- گزینه Forward را انتخاب کنید.
- URL هدف را وارد کنید؛ مثلا
http://localhost:3000/webhook.
پاسخ مستقیم
اگر provider انتظار پاسخ خاصی دارد، می‌توانید همان پاسخ را در Postman تنظیم کنید:
- در تب Routing گزینه Respond را انتخاب کنید.
- Status code مثل
200را وارد کنید. - در صورت نیاز header و body پاسخ را تنظیم کنید.
استفاده از مقدارهای request ورودی
در response body و response headers می‌توانید با template syntax به مقدارهای request ورودی دسترسی داشته باشید:
{{$body 'challenge'}}
{{$headers 'x-event-id'}}
{{$query 'token'}}برای فیلدهای تو در تو هم می‌توانید از مسیر object استفاده کنید؛ مثل {{$body 'event.user.id'}}.
محافظت از endpoint
برای اطمینان از اینکه event از producer قابل اعتماد آمده است، می‌توانید auth verification تنظیم کنید. ابتدا در تب Settings یک environment به listener وصل کنید؛ چون secretها از environment variables خوانده می‌شوند. سپس در بخش Endpoint Auth نوع احراز هویت، کلید header و مقدارهای لازم مثل API key یا username/password را وارد کنید.
Replay کردن eventها
هر event ثبت‌شده را می‌توانید دوباره اجرا کنید. Postman همان header و body خام را دوباره از مسیر routing فعلی عبور می‌دهد. این کار برای دیباگ handler محلی، بررسی یک fix، و تست idempotency بسیار مفید است.
منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.