ทดสอบ Polar Webhook ในเครื่องด้วย Polar CLI

หากต้องการทดสอบ Polar webhooks ในเครื่อง ให้เรียกใช้ตัวจัดการ webhook ติดตั้งและตรวจสอบสิทธิ์ Polar CLI จากนั้นจึงใช้งาน polar listen http://localhost:3000/api/webhooks/polar เพื่อถ่ายทอดเหตุการณ์ที่เซ็นชื่อไปยังเครื่องของคุณโดยตรง คัดลอกความลับชั่วคราวที่ผู้ฟังพิมพ์ลงไป POLAR_WEBHOOK_SECRETตรวจสอบเนื้อหาดิบก่อนที่จะประมวลผล และทริกเกอร์การชำระเงินแบบแซนด์บ็อกซ์ คำสั่งซื้อ การคืนเงิน หรือการสมัครสมาชิก

เหตุใด Polar CLI จึงเป็นขั้นตอนการทำงานภายในเครื่องที่ง่ายที่สุด

ปลายทาง Webhook ที่ใช้งานจริงตามปกติต้องเข้าถึงได้แบบสาธารณะผ่าน HTTPS Polar นำเสนอ Local Listener ที่สร้างขึ้นตามวัตถุประสงค์ ดังนั้นคุณไม่จำเป็นต้องสร้างจุดสิ้นสุดถาวรหรือวาง URL โทรกลับชั่วคราวลงในแดชบอร์ดซ้ำๆ CLI เชื่อมต่อกับองค์กรของคุณ แสดงความลับในการลงนามเซสชัน รับกิจกรรม และส่งต่อไปยัง URL ในเครื่องที่คุณระบุ

อย่างเป็นทางการของโพลาร์ เอกสาร webhook ท้องถิ่น การใช้งาน polar listen http://localhost:3000/. ชี้ไปที่เส้นทางที่สมบูรณ์เมื่อแอปพลิเคชันของคุณจัดการ webhooks ด้านล่างเส้นทางเช่น /api/webhooks/polar. วิธีนี้จะตรวจจับข้อผิดพลาดของเส้นทางก่อนการใช้งานจริงและคงตัวจัดการแอปพลิเคชันเดิมที่คุณต้องการปรับใช้

ติดตั้ง CLI และเริ่มฟัง

1. เริ่มแอปพลิเคชันของคุณและยืนยันว่าเส้นทาง POST นั้นมีอยู่ในเครื่อง
2. ติดตั้ง Polar CLI โดยใช้คำสั่งจากเอกสารอย่างเป็นทางการ
3. วิ่ง polar login และอนุมัติบัญชีที่ถูกต้อง
4. เริ่ม polar listen http://localhost:3000/api/webhooks/polar.
5. เลือกองค์กรที่เป็นเจ้าของผลิตภัณฑ์แซนด์บ็อกซ์ของคุณ
6. คัดลอกความลับของเซสชันที่แสดงลงใน POLAR_WEBHOOK_SECRET และรีสตาร์ทแอปของคุณหากมีการโหลดสภาพแวดล้อมเมื่อเริ่มต้นเท่านั้น
7. ทริกเกอร์การดำเนินการแซนด์บ็อกซ์และเปรียบเทียบสถานะการจัดส่ง CLI กับบันทึกในเครื่องของคุณ

ข้อมูลลับของผู้ฟังเป็นส่วนหนึ่งของเซสชันภายในเครื่อง อย่าถือว่าเท่ากับข้อมูลลับปลายทางของแดชบอร์ดหรือนำค่าที่ใช้งานจริงมาใช้ซ้ำ หากคุณเชื่อมต่อใหม่และได้รับข้อมูลลับอื่น ให้อัปเดตสภาพแวดล้อมในเครื่องก่อนทำการทดสอบอีกครั้ง

สร้างตัวจัดการเราเตอร์แอป Next.js

Polar เป็นไปตามข้อกำหนด Standard Webhooks การจัดส่งประกอบด้วย webhook-id, webhook-timestamp, และ webhook-signature. การยืนยันต้องใช้เนื้อหาคำขอดิบที่แน่นอน กำลังโทร request.json() ขั้นแรกและทำให้วัตถุเป็นอนุกรมอีกครั้งสามารถเปลี่ยนไบต์ที่เซ็นชื่อได้

// app/api/webhooks/polar/route.ts
import { Webhook } from 'standardwebhooks';

export const runtime = 'nodejs';

export async function POST(request: Request) {
  const rawBody = await request.text();
  const secret = process.env.POLAR_WEBHOOK_SECRET;
  if (!secret) {
    return new Response('Webhook secret is not configured', { status: 500 });
  }

  const headers = {
    'webhook-id': request.headers.get('webhook-id') ?? '',
    'webhook-timestamp': request.headers.get('webhook-timestamp') ?? '',
    'webhook-signature': request.headers.get('webhook-signature') ?? '',
  };

  try {
    const encodedSecret = Buffer.from(secret.trim(), 'utf8').toString('base64');
    const payload = new Webhook(encodedSecret).verify(rawBody, headers);
    await acceptPolarEvent(headers['webhook-id'], payload);
    return Response.json({ received: true });
  } catch {
    return new Response('Invalid signature', { status: 403 });
  }
}

โพลาร์ เอกสารการจัดส่ง เรียกกับดักการตรวจสอบแบบกำหนดเองทั่วไป: ไลบรารี Webhooks มาตรฐานคาดหวังความลับที่เข้ารหัส Base64 ในขณะที่ Polar จัดเตรียมสตริงลับปกติ ตัวช่วย Polar SDK จัดการการแปลงนี้โดยอัตโนมัติ เมื่อใช้ standardwebhooks โดยตรง Base64 เข้ารหัส Polar Secret ที่สมบูรณ์ดังที่แสดงด้านบน

ต้องการอะแดปเตอร์เฟรมเวิร์กอย่างเป็นทางการเมื่อพร้อมใช้งาน

Polar เผยแพร่อะแดปเตอร์ที่รวมการตรวจสอบลายเซ็นเข้ากับตัวจัดการเพย์โหลดที่พิมพ์ อย่างเป็นทางการ เอกสารประกอบของอะแดปเตอร์ด่วน ให้การติดต่อกลับแบบละเอียดสำหรับการชำระเงิน การสั่งซื้อ การคืนเงิน สิทธิประโยชน์ และเหตุการณ์การสมัครสมาชิก อะแดปเตอร์ช่วยลดโอกาสในการใช้การแยกวิเคราะห์ส่วนหัวหรือการเข้ารหัสลับอย่างไม่ถูกต้อง

import express from 'express';
import { Webhooks } from '@polar-sh/express';

const app = express();
app.use(express.json());
app.post('/webhooks/polar', Webhooks({
  webhookSecret: process.env.POLAR_WEBHOOK_SECRET,
  onOrderPaid: async (event) => {
    await queueOrderPaid(event.data);
  },
  onSubscriptionActive: async (event) => {
    await queueSubscriptionActive(event.data);
  },
}));
app.listen(3000);

ปฏิบัติตามลำดับมิดเดิลแวร์ที่บันทึกไว้ของอแด็ปเตอร์สำหรับเวอร์ชันที่คุณติดตั้ง หากคุณใช้ตัวตรวจสอบทั่วไปแทน ให้รักษาข้อมูลดิบไว้อย่างชัดเจน อย่าผสมอะแดปเตอร์ที่อ่านสตรีมกับมิดเดิลแวร์ที่ใช้งานก่อน

คุณควรทดสอบเหตุการณ์ Polar ใด

กิจกรรมการชำระเงิน

กิจกรรมการชำระเงินช่วยติดตามเซสชันก่อนที่จะกลายเป็นคำสั่งซื้อแบบชำระเงิน ทดสอบการดำเนินการให้เสร็จสิ้นและละทิ้งหรืออัปเดตสถานะโดยไม่ต้องให้สิทธิ์เข้าถึงเพียงเพราะมีการสร้างการชำระเงินแล้ว คำสั่งซื้อที่ชำระเงินหรือการสมัครสมาชิกที่ใช้งานอยู่ควรยังคงเป็นสัญญาณการให้สิทธิ์ที่เชื่อถือได้

คำสั่งซื้อที่ชำระเงินและคืนเงินแล้ว

สำหรับกิจกรรมที่ชำระเงินตามคำสั่งซื้อ ให้แมปลูกค้าและผลิตภัณฑ์ Polar กับบัญชีภายในของคุณ จากนั้นให้สิทธิ์สิทธิประโยชน์ที่ซื้อเพียงครั้งเดียว กิจกรรมการคืนเงินควรย้อนกลับเฉพาะการให้สิทธิ์ที่ได้รับผลกระทบตามนโยบายการคืนเงินของคุณ รหัสผู้ให้บริการร้านค้าเพื่อให้ฝ่ายสนับสนุนสามารถกระทบยอดกิจกรรมกับ Polar

เหตุการณ์วงจรการสมัครใช้งาน

ทดสอบการสร้าง การเปิดใช้งาน การอัปเดต การยกเลิก การเพิกถอน และพฤติกรรมการพ้นกำหนดชำระที่ผลิตภัณฑ์ของคุณรองรับ คำขอยกเลิกอาจไม่ได้หมายความว่าการเข้าถึงจะสิ้นสุดลงทันที สถานะร้านค้าและวันที่มีผลบังคับใช้ แทนที่จะลดวงจรชีวิตลงเหลือเพียงวงจรเดียว is_active ธง.

เงินช่วยเหลือ

หากการบูรณาการของคุณใช้สิทธิประโยชน์ของ Polar การสร้างทุนทดสอบ การอัปเดต และการเพิกถอนโดยแยกจากเหตุการณ์การเรียกเก็บเงิน ทำให้ตัวจัดการมาบรรจบกันในสถานะที่ต้องการ ดังนั้นการได้รับสิทธิ์เดียวกันสองครั้งจึงไม่จัดเตรียมทรัพยากรที่ซ้ำกัน

ทำให้ทุกเหตุการณ์เป็น idempotent

การจัดส่งผ่านเครือข่ายไม่ใช่การทำธุรกรรมเพียงครั้งเดียว ตัวจัดการสามารถคอมมิตงานฐานข้อมูลและสูญเสียการตอบสนอง ส่งผลให้ผู้ส่งลองอีกครั้ง ใช้ webhook-id เป็นรหัสการจัดส่งที่ไม่ซ้ำกันและอ้างสิทธิ์ในธุรกรรมเดียวกันกับที่อัปเดตสถานะแอปพลิเคชันของคุณ

await db.transaction(async (tx) => {
  const firstDelivery = await tx.webhookReceipts.insertIfAbsent({
    provider: 'polar',
    deliveryId: webhookId,
  });
  if (!firstDelivery) return;

  await applyPolarEvent(tx, payload);
  await tx.outbox.enqueue('polar-event-accepted', { webhookId });
});

ส่งคืนการตอบกลับ 2xx สำหรับสำเนาที่เสร็จสมบูรณ์แล้ว อย่ากรองข้อมูลที่ซ้ำกันตามรหัสลูกค้าหรือการสมัครใช้งานเท่านั้น เนื่องจากเหตุการณ์ที่ถูกต้องตามกฎหมายจำนวนมากกำหนดเป้าหมายไปที่ทรัพยากรเดียวกัน ที่ คู่มือการลองซ้ำของ webhook และ idempotency ครอบคลุมรูปแบบกล่องจดหมายและกล่องจดหมายออกโดยละเอียดยิ่งขึ้น

รับทราบผลงานสั้น ๆ

ตรวจสอบคำขอ คงอยู่หรือจัดคิวงานที่คงทน และส่งคืนความสำเร็จ อีเมล การสร้างใบอนุญาต การเข้าถึงพื้นที่เก็บข้อมูล การวิเคราะห์ และการเรียก API ของบริษัทอื่นควรทำงานแบบอะซิงโครนัส การตอบรับอย่างรวดเร็วช่วยลดการลองใหม่ในขณะที่การเขียนที่คงทนจะป้องกันไม่ให้เหตุการณ์หายไปหากกระบวนการออกหลังจากส่งคืน

ประเภทเหตุการณ์ที่ไม่รู้จักควรได้รับการบันทึกและรับทราบหลังจากการตรวจสอบลายเซ็นที่ถูกต้อง Polar สามารถเพิ่มประเภทเหตุการณ์เมื่อเวลาผ่านไป การโยนค่าที่ไม่คุ้นเคยทุกค่าจะแปลงการเพิ่มสคีมาที่ไม่เป็นอันตรายเป็นความล้มเหลวในการจัดส่งซ้ำๆ

แก้ไขปัญหาความล้มเหลวของโฮสต์ท้องถิ่นของ Polar webhook

CLI เชื่อมต่อแต่เส้นทางส่งคืน 404

ผ่านเส้นทางท้องถิ่นเต็มรูปแบบไปที่ polar listenไม่ใช่แค่ท่าเรือเท่านั้น ใน Next.js App Router ตรวจสอบให้แน่ใจว่าได้ตั้งชื่อไฟล์แล้ว route.ts และการส่งออก POST. เบราว์เซอร์ GET ที่ส่งคืน 404 ไม่ได้พิสูจน์ว่าเส้นทาง POST หายไป ดังนั้นให้ทดสอบด้วย curl -X POST.

ทุกคำขอส่งคืน 403

ยืนยันว่าแอปโหลดข้อมูลลับที่พิมพ์โดยเซสชัน CLI ปัจจุบัน รักษาเนื้อความดิบและส่วนหัว Webhooks มาตรฐานทั้งสามไว้ หากคุณใช้ไลบรารีทั่วไป Base64 จะเข้ารหัส Polar Secret เพียงครั้งเดียว หากคุณใช้ตัวช่วย Polar SDK ให้ส่งความลับดั้งเดิมและปล่อยให้ SDK จัดการการเข้ารหัส

ไม่มีกิจกรรมปรากฏขึ้นหลังการชำระเงิน

ตรวจสอบว่า CLI เชื่อมต่อกับองค์กรและสภาพแวดล้อมเดียวกันกับที่เกิดการกระทำ เปิดเทอร์มินัล Listener ไว้ ใช้ทรัพยากรแซนด์บ็อกซ์ และยืนยันว่าการดำเนินการของคุณไปถึงสถานะกิจกรรมที่คุณสมัครรับข้อมูลจริงๆ

กิจกรรมได้รับการประมวลผลสองครั้ง

เพิ่มข้อจำกัดเฉพาะสำหรับ webhook-id และคืนความสำเร็จให้กับการทำซ้ำ ตรวจสอบว่ามีข้อยกเว้นเกิดขึ้นหลังจากการอัปเดตสถานะของคุณ แต่ก่อนการตอบกลับ ย้ายผลข้างเคียงที่ช้าไปยังผู้ปฏิบัติงานที่ได้รับการสนับสนุนจากกล่องขาออก

คำขอที่บันทึกไว้เก่าไม่ผ่านการตรวจสอบ

การตรวจสอบ Webhooks มาตรฐานจะมีการประทับเวลาเพื่อจำกัดการโจมตีซ้ำ การจับภาพเก่าควรไม่ผ่านหน้าต่างการตรวจสอบปกติ สำหรับการทดสอบตรรกะทางธุรกิจ ให้ตรวจสอบการจัดส่งใหม่หนึ่งครั้งและบันทึกการติดตั้งเพย์โหลดที่ผ่านการฆ่าเชื้อไว้ด้านหลังขอบเขตการรับรองความถูกต้อง

รายการตรวจสอบความปลอดภัยก่อนการผลิต

• ใช้ความลับปลายทางภายใน แซนด์บ็อกซ์ และการใช้งานจริงที่แยกจากกัน
• ตรวจสอบเนื้อหาดิบ การประทับเวลา รหัสการจัดส่ง และลายเซ็นก่อนประมวลผล
• เก็บโทเค็น API และความลับของเว็บฮุคไว้ในตัวแปรสภาพแวดล้อมแบบเซิร์ฟเวอร์เท่านั้น
• ทำซ้ำโดย webhook-id และตรวจสอบผลิตภัณฑ์ องค์กร และตัวระบุลูกค้า
• ตรวจทานอีเมลลูกค้า ข้อมูลการเรียกเก็บเงิน ข้อมูลเมตา และเพย์โหลดทั้งหมดจากบันทึกที่แชร์
• ใช้ขีดจำกัดขนาดคำขอและตรวจสอบลายเซ็นที่ไม่ถูกต้องซ้ำๆ
• แทนที่ Listener ในเครื่องด้วยตำแหน่งข้อมูล HTTPS ที่เสถียร และทดสอบโฟลว์แซนด์บ็อกซ์ใหม่ก่อนเปิดใช้งานผลิตภัณฑ์ที่ใช้งานจริง

Polar CLI จะลบลูปการปรับใช้ แต่ไม่ควรลบการควบคุมการผลิต เปิดใช้งานการตรวจสอบลายเซ็น การระบุตำแหน่ง การกรองเหตุการณ์ และการประมวลผลที่คงทนในเครื่อง เพื่อให้โค้ดที่คุณทดสอบคือโค้ดที่คุณจัดส่ง สำหรับรายละเอียดการตรวจสอบที่ไม่ขึ้นอยู่กับกรอบงาน โปรดอ่าน คู่มือการตรวจสอบลายเซ็น Webhook และทั่วไป เวิร์กโฟลว์การดีบักในเครื่อง.