اندپوینتها
`webhooks.list`، `get`، `create`، `update`، `delete`، `rotateSecret`، `test` و `listDeliveries`.
همهٔ متدها
const endpoint = await openemail.webhooks.create({ url: 'https://acme.com/hooks/mail', eventTypes: ['email.sent', 'email.bounced'], description: 'Billing service',}) await store(endpoint.secret) await openemail.webhooks.list()await openemail.webhooks.get(endpoint.id)await openemail.webhooks.update(endpoint.id, { enabled: false })await openemail.webhooks.test(endpoint.id)const rotated = await openemail.webhooks.rotateSecret(endpoint.id)await openemail.webhooks.delete(endpoint.id)create جز rotateSecret تنها جایی است که کلید مخفی بازگردانده میشود. خواندن هرگز آن را بازتاب نمیدهد، پس پیش از هر کار دیگری ذخیرهاش کنید. برای دریافت هر رویدادی، از جمله رویدادهای بعدی، eventTypes را ندهید.
rotateSecret هیچ پنجرهٔ همپوشانی ندارد. کلید مخفی قدیمی بیدرنگ از کار میافتد، پس پیش از چرخاندن، کلید تازه را مستقر کنید. هرگز خودکار دوباره تلاش نمیشود: تلاش مجدد بار دوم میچرخاند و کلید مخفیای را که تلاش اول برگردانده بود باطل میکند.
چه چیزهایی را میتوان اشتراک گرفت
WEBHOOK_EVENTS export میشود تا بتوانید فهرست را رندر کنید. رویدادها، رویدادهای **صندوق پستی** هستند نه این API: email.received برای ایمیلی که در اپ میرسد شلیک میشود، و email.sent برای پیامی که کامپوزر فرستاده است. مشترک شدن با تماشای ترافیک API خودتان یکی نیست.
اثبات اینکه کار میکند
const result = await openemail.webhooks.test('whe_…')console.log(result.delivery?.status, result.delivery?.responseCode) const deliveries = await openemail.webhooks.listDeliveries('whe_…')for (const d of deliveries) console.log(d.eventType, d.status, d.responseCode, d.error)یک responseCode برابر null یعنی اصلاً پاسخی وجود نداشته است (DNS، TLS، یک تایماوت)، که واقعیتی متفاوت از پاسخی است که 0 گفته باشد. هر ردیف attempt و maxAttempts را با خود دارد، پس چند ردیف میتوانند یک رویداد را توصیف کنند: payload.id یکسان در میان آنها همان رویداد است و شمارهٔ تلاش، همان کوشش.
پارامترها: webhooks.create
urlstringالزامی- جایی که تحویلها با POST به آن فرستاده میشوند. فقط HTTPS، و host نمیتواند `localhost`، نامی با پسوند `.localhost`/`.local`/`.internal`، یا یک IP لفظی loopback، خصوصی، CGNAT یا link-local باشد. این یک fetch سمت سرور به آدرسی است که شما میدهید، پس چنین مواردی روی `url` یک 422 هستند؛ بررسی، hostname را همانطور که نوشته شده میخواند و هرگز DNS را resolve نمیکند. آنچه ذخیره میشود سریالسازی تجزیهگر URL از چیزی است که فرستادهاید، پس `https://acme.com` بهصورت `https://acme.com/` بازخوانده میشود.
eventTypesWebhookEvent[]- کدام رویدادها به این اندپوینت میرسند: هرکدام از نامهای موجود در `WEBHOOK_EVENTS`. `POST /webhooks` آرایه را به تعداد رویدادهای موجود سقف میزند، پس یکی بیشتر از آن روی `eventTypes` یک 422 است؛ `PATCH` سقف نمیزند. تنها طول سقف دارد، و نام تکراری دقیقاً همانگونه که فرستادهاید ذخیره و بازخوانده میشود. نبودن یا خالی بودن بهصورت فهرستی خالی ذخیره میشود، و به همین دلیل است که بهصورت `['*']` بازخوانده میشود، و معنایش هر رویداد `email.*` جز `email.replied` است، امروز چهارده مورد، و هرگز خانوادههای دامنه یا suppression. خانوادهای که بعداً افزوده شود هرگز به اندپوینتی که نامش را نبرده نمیرسد، پس یک یکپارچهسازی نمیتواند بهخاطر یک انتشار شروع به دریافت شکلی کند که هرگز ندیده است.
descriptionstring- برچسبی برای اندپوینت، حداکثر 200 نویسه، تا فهرست وبهوکها بهصورت نامها خوانده شود نه ستونی از URLها. اگر داده نشود، بهصورت null ذخیره و بازگردانده میشود.
پاسخ: CreatedWebhookResource
object'webhook'- همیشه `'webhook'`، همان تفکیکگری که یک خواندن ساده برمیگرداند، چون کلید مخفی یک کلید اضافه روی همان شکل معمول است نه یک نوع object جداگانه. اینکه `secret` حاضر باشد یا نه با متدی که صدا زدهاید تعیین میشود، نه با این فیلد.
idstring- شناسهٔ اندپوینت: `whe_` و پس از آن 24 نویسهٔ hex. هر فراخوانی دیگر وبهوک آن را میگیرد: `get`، `update`، `delete`، `rotateSecret`، `test` و `listDeliveries`.
urlstring- اندپوینت همانگونه که ذخیره شده است، پس از گذراندن بررسیهای HTTPS و host مسدود. این همان URL تجزیهشده است که دوباره سریال شده، پس بهجای رشتهای که فرستادهاید با این مقدار مقایسه کنید.
descriptionstring | null- برچسبی که دادهاید، یا اگر چیزی ندادهاید null. یک `update` که null صریح بفرستد آن را دوباره به null بازمیگرداند.
eventTypesWebhookEvent[] | ['*']- رویدادهای مشترکشده، یا وقتی اندپوینت هیچکدام را نام نبرده باشد `['*']`. `['*']` شیوهٔ رندر شدن یک فهرست ذخیرهشدهٔ خالی هنگام خواندن است و نمیتوان آن را بازفرستاد، و نمایندهٔ سیزده رویداد پیام است نه کل فهرست. `create` و `update` تنها نامهای واقعی رویدادها را میپذیرند.
enabledboolean- اینکه تحویلها تلاش میشوند یا نه؛ اندپوینت غیرفعال هنگام توزیع رویدادها رد میشود و کلید مخفی و تاریخچهٔ تحویلش را نگه میدارد. اینجا همیشه true است، چون `WebhookCreate` فیلد `enabled` ندارد و تنها `WebhookPatch` دارد.
lastDeliveryAtstring | null- مهر زمانی ISO 8601 آخرین تلاشِ تحویل، نه آخرین موفقیت. پس از یک POST ناموفق هم ثبت میشود، پس به شما میگوید اندپوینت آزموده شده است و `listDeliveries` میگوید چطور پیش رفت. تا نخستین تلاش null است، و بنابراین روی `create` همیشه null.
createdAtstring- مهر زمانی ISO 8601 زمانی که اندپوینت ثبت شده است. `list` اندپوینتها را بر اساس همین فیلد از تازهترین بازمیگرداند.
secretstring- کلید HMAC-SHA-256 که `X-OpenEmail-Signature` هر تحویل را امضا میکند: `whsec_` و پس از آن 32 بایت تصادفی بهصورت base64url، و همان چیزی که به `verifyWebhookSignature` میدهید. تنها `create` و `rotateSecret` آن را برمیگردانند و بس. خواندن هرگز آن را بازتاب نمیدهد، پس همین حالا ذخیرهاش کنید؛ کلید مخفی گمشده را تنها با `rotateSecret` میتوان جایگزین کرد، که قدیمی را بیدرنگ باطل میکند.