Làm cách nào để kiểm tra Polar webhook cục bộ?

Chạy trình xử lý cục bộ của bạn, xác thực Polar CLI, thực thi quá trình nghe cực bằng URL webhook localhost hoàn chỉnh, sao chép bí mật được hiển thị vào POLAR_WEBHOOK_SECRET và kích hoạt sự kiện hộp cát.

Tôi có cần đường hầm công cộng cho Polar webhook không?

Không phải khi sử dụng trình nghe CLI của Polar. Nó chuyển tiếp các sự kiện của tổ chức tới URL localhost mà bạn cung cấp. Điểm cuối webhook của trang tổng quan thông thường vẫn cần URL HTTPS có thể truy cập công khai.

Tại sao chữ ký webhook Polar của tôi không thành công?

Các nguyên nhân phổ biến là sử dụng bí mật của trình nghe cũ, phân tích cú pháp JSON trước khi xác minh, bỏ qua tiêu đề Webhooks tiêu chuẩn hoặc quên mã hóa Base64 bí mật Polar khi sử dụng trình xác minh chung.

Làm cách nào để ngăn chặn quá trình xử lý webhook Polar trùng lặp?

Lưu trữ webhook-id dưới một ràng buộc cơ sở dữ liệu duy nhất và áp dụng sự kiện đó trong cùng một giao dịch. Trả về thành công khi ID giao hàng đã được hoàn thành.

Kiểm thử webhook Polar cục bộ bằng Polar CLI

Để kiểm tra Polar webhooks cục bộ, hãy chạy trình xử lý webhook của bạn, cài đặt và xác thực Polar CLI, sau đó sử dụng polar listen http://localhost:3000/api/webhooks/polar để chuyển tiếp các sự kiện đã ký trực tiếp đến máy của bạn. Sao chép bí mật tạm thời được người nghe in vào POLAR_WEBHOOK_SECRET, xác minh nội dung thô trước khi xử lý và kích hoạt sự kiện thanh toán, đặt hàng, hoàn tiền hoặc đăng ký hộp cát.

Tại sao Polar CLI là quy trình làm việc cục bộ đơn giản nhất

Điểm cuối webhook sản xuất thông thường phải có thể truy cập công khai qua HTTPS. Polar cung cấp trình nghe cục bộ được xây dựng có mục đích, do đó bạn không cần phải tạo điểm cuối cố định hoặc liên tục dán các URL gọi lại tạm thời vào trang tổng quan. CLI kết nối với tổ chức của bạn, hiển thị bí mật ký phiên, nhận sự kiện và chuyển tiếp chúng tới URL cục bộ mà bạn cung cấp.

Quan chức của Polar tài liệu webhook cục bộ công dụng polar listen http://localhost:3000/. Trỏ nó vào đường dẫn đầy đủ khi ứng dụng của bạn xử lý các webhook bên dưới một tuyến đường, chẳng hạn như /api/webhooks/polar. Điều này phát hiện các lỗi đường dẫn trước khi sản xuất và giữ nguyên trình xử lý ứng dụng mà bạn dự định triển khai.

Cài đặt CLI và bắt đầu nghe

Khởi động ứng dụng của bạn và xác nhận tuyến POST của nó có sẵn cục bộ.
Cài đặt Polar CLI bằng lệnh từ tài liệu chính thức.
Chạy polar login và ủy quyền đúng tài khoản.
Bắt đầu polar listen http://localhost:3000/api/webhooks/polar.
Chọn tổ chức sở hữu sản phẩm hộp cát của bạn.
Sao chép bí mật phiên được hiển thị vào POLAR_WEBHOOK_SECRET và khởi động lại ứng dụng của bạn nếu môi trường của nó chỉ được tải khi khởi động.
Kích hoạt hành động hộp cát và so sánh trạng thái phân phối CLI với nhật ký cục bộ của bạn.

Bí mật của người nghe là một phần của phiên cục bộ. Đừng cho rằng nó tương đương với bí mật điểm cuối của bảng thông tin hoặc sử dụng lại giá trị sản xuất. Nếu bạn kết nối lại và nhận được một bí mật khác, hãy cập nhật môi trường cục bộ trước khi kiểm tra lại.

Tạo trình xử lý Bộ định tuyến ứng dụng Next.js

Polar tuân theo đặc tả Webhooks tiêu chuẩn. Một lần giao hàng bao gồm webhook-id, webhook-timestampvà webhook-signature. Việc xác minh phải sử dụng nội dung yêu cầu thô chính xác; đang gọi điện request.json() đầu tiên và tuần tự hóa lại đối tượng có thể thay đổi các byte đã ký.

// 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 });
  }
}

của Polar tài liệu giao hàng đưa ra một bẫy xác minh tùy chỉnh phổ biến: Các thư viện Webhooks tiêu chuẩn mong đợi một bí mật được mã hóa Base64, trong khi Polar cung cấp một chuỗi bí mật bình thường. Người trợ giúp Polar SDK tự động xử lý chuyển đổi này. Khi sử dụng standardwebhooks trực tiếp, Base64 mã hóa bí mật Polar hoàn chỉnh như được hiển thị ở trên.

Ưu tiên bộ điều hợp khung chính thức khi có sẵn

Polar xuất bản các bộ điều hợp kết hợp xác minh chữ ký với trình xử lý tải trọng đã nhập. quan chức Tài liệu bộ chuyển đổi nhanh cung cấp lệnh gọi lại chi tiết cho các sự kiện thanh toán, đặt hàng, hoàn tiền, lợi ích và đăng ký. Bộ điều hợp giúp giảm nguy cơ triển khai phân tích cú pháp tiêu đề hoặc mã hóa bí mật không chính xác.

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);

Thực hiện theo thứ tự phần mềm trung gian được ghi trong tài liệu của bộ điều hợp cho phiên bản bạn cài đặt. Thay vào đó, nếu bạn sử dụng trình xác minh chung, hãy bảo quản phần thân thô một cách rõ ràng. Không kết hợp bộ điều hợp đọc luồng với phần mềm trung gian sử dụng nó trước.

Bạn nên thử nghiệm những sự kiện Polar nào?

Sự kiện thanh toán

Sự kiện thanh toán giúp theo dõi phiên trước khi phiên đó trở thành đơn đặt hàng thanh toán. Kiểm tra việc hoàn thành thành công và các trạng thái bị bỏ qua hoặc cập nhật mà không cấp quyền truy cập chỉ vì quá trình thanh toán đã được tạo. Đơn đặt hàng đã thanh toán hoặc đăng ký đang hoạt động phải vẫn là tín hiệu có thẩm quyền.

Đơn hàng đã thanh toán và được hoàn tiền

Đối với sự kiện thanh toán theo đơn đặt hàng, hãy liên kết khách hàng và sản phẩm Polar với tài khoản nội bộ của bạn, sau đó cấp quyền lợi đã mua đúng một lần. Các sự kiện hoàn tiền chỉ được đảo ngược quyền lợi bị ảnh hưởng theo chính sách hoàn tiền của bạn. Lưu trữ ID nhà cung cấp để bộ phận hỗ trợ có thể điều chỉnh sự kiện với Polar.

Sự kiện vòng đời đăng ký

Kiểm tra việc tạo, kích hoạt, cập nhật, hủy, thu hồi và mọi hành vi quá hạn mà sản phẩm của bạn hỗ trợ. Yêu cầu hủy có thể không có nghĩa là quyền truy cập sẽ kết thúc ngay lập tức. Lưu trữ trạng thái và ngày có hiệu lực thay vì giảm vòng đời xuống còn một is_active cờ.

Trợ cấp phúc lợi

Nếu tiện ích tích hợp của bạn sử dụng các lợi ích của Polar, thì việc tạo, cập nhật và thu hồi cấp phép thử nghiệm sẽ độc lập với các sự kiện thanh toán. Làm cho các trình xử lý hội tụ về trạng thái mong muốn để việc nhận cùng một khoản trợ cấp hai lần sẽ không cung cấp các tài nguyên trùng lặp.

Làm cho mọi sự kiện trở nên bình thường

Phân phối mạng không phải là giao dịch chính xác một lần. Trình xử lý có thể thực hiện công việc cơ sở dữ liệu của nó và mất phản hồi, khiến người gửi phải thử lại. sử dụng webhook-id làm khóa phân phối duy nhất và xác nhận nó trong cùng một giao dịch cập nhật trạng thái ứng dụng của bạn.

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 });
});

Trả về phản hồi 2xx cho bản sao đã được hoàn thành. Không loại bỏ trùng lặp chỉ theo ID khách hàng hoặc ID đăng ký vì nhiều sự kiện hợp pháp nhắm mục tiêu vào cùng một tài nguyên. các hướng dẫn thử lại webhook và idempotency bao gồm các mẫu hộp thư đến và hộp thư đi chi tiết hơn.

Giữ công việc xác nhận ngắn gọn

Xác minh yêu cầu, duy trì nó hoặc xếp hàng một công việc lâu dài và trả lại thành công. Email, tạo giấy phép, truy cập kho lưu trữ, phân tích và lệnh gọi API của bên thứ ba sẽ chạy không đồng bộ. Xác nhận nhanh giúp giảm số lần thử lại trong khi việc ghi lâu bền sẽ ngăn các sự kiện biến mất nếu quá trình thoát ra sau khi quay trở lại.

Các loại sự kiện không xác định phải được ghi lại và xác nhận sau khi xác minh chữ ký hợp lệ. Polar có thể thêm các loại sự kiện theo thời gian; việc đưa vào mọi giá trị không quen thuộc sẽ biến việc bổ sung lược đồ vô hại thành các lỗi phân phối lặp đi lặp lại.

Khắc phục sự cố lỗi localhost của Polar webhook

CLI kết nối nhưng tuyến trả về 404

Vượt qua toàn bộ tuyến đường địa phương tới polar listen, không chỉ có cảng. Trong Bộ định tuyến ứng dụng Next.js, hãy đảm bảo tệp được đặt tên route.ts và xuất khẩu POST. Trình duyệt GET trả về 404 không chứng minh được tuyến POST bị thiếu, vì vậy hãy kiểm tra với curl -X POST.

Mọi yêu cầu đều trả về 403

Xác nhận ứng dụng đã tải bí mật được in bởi phiên CLI hiện tại. Giữ nguyên phần thân thô và cả ba tiêu đề Webhooks tiêu chuẩn. Nếu bạn sử dụng thư viện chung, Base64 sẽ mã hóa bí mật Polar chính xác một lần; nếu bạn sử dụng trình trợ giúp Polar SDK, hãy chuyển bí mật ban đầu và để SDK xử lý việc mã hóa.

Không có sự kiện nào xuất hiện sau khi thanh toán

Xác minh CLI được kết nối với cùng tổ chức và môi trường nơi hành động xảy ra. Luôn mở thiết bị nghe đầu cuối, sử dụng tài nguyên hộp cát và xác nhận hành động của bạn thực sự đạt đến trạng thái sự kiện mà bạn đã đăng ký.

Sự kiện được xử lý hai lần

Thêm một ràng buộc duy nhất cho webhook-id và trả lại thành công cho các bản sao. Kiểm tra xem có ngoại lệ xảy ra sau khi cập nhật trạng thái của bạn nhưng trước phản hồi hay không. Di chuyển các tác dụng phụ chậm vào một công cụ hỗ trợ hộp thư đi.

Yêu cầu được ghi lại cũ không được xác minh

Xác minh Webhooks tiêu chuẩn bao gồm dấu thời gian để hạn chế các cuộc tấn công lặp lại. Một bản chụp cũ sẽ không vượt qua được cửa sổ xác minh thông thường. Đối với các thử nghiệm logic nghiệp vụ, hãy xác minh lần phân phối mới một lần và lưu cố định trọng tải đã được dọn dẹp phía sau ranh giới xác thực.

Danh sách kiểm tra an ninh trước khi sản xuất

Sử dụng các bí mật cục bộ, hộp cát và điểm cuối sản xuất riêng biệt.
Xác minh nội dung thô, dấu thời gian, ID gửi và chữ ký trước khi xử lý.
Giữ mã thông báo API và bí mật webhook trong các biến môi trường chỉ dành cho máy chủ.
Loại bỏ trùng lặp bởi webhook-id và xác nhận thông tin nhận dạng sản phẩm, tổ chức và khách hàng.
Biên tập lại email khách hàng, dữ liệu thanh toán, siêu dữ liệu và tải trọng đầy đủ từ nhật ký được chia sẻ.
Áp dụng giới hạn kích thước yêu cầu và giám sát các chữ ký không hợp lệ lặp đi lặp lại.
Thay thế trình nghe cục bộ bằng điểm cuối HTTPS ổn định và kiểm tra luồng hộp cát mới trước khi bật các sản phẩm trực tiếp.

Polar CLI loại bỏ vòng triển khai nhưng không loại bỏ các biện pháp kiểm soát sản xuất. Luôn bật xác minh chữ ký, tính tạm thời, lọc sự kiện và xử lý lâu dài cục bộ để mã bạn kiểm tra chính là mã bạn gửi. Để biết chi tiết xác minh độc lập với khung, hãy đọc hướng dẫn xác minh chữ ký webhook và cái chung quy trình gỡ lỗi cục bộ.