Webhook

Webhook cho phép ứng dụng của bạn nhận thông báo sự kiện thời gian thực từ PDFSimple. Thay vì liên tục kiểm tra trạng thái tác vụ qua API, hãy đăng ký endpoint và PDFSimple sẽ POST dữ liệu có ký chữ ký đến đó khi sự kiện xảy ra.

Thiết lập webhook

1. Vào Bảng điều khiển → Webhook và nhấp Thêm endpoint.
2. Nhập URL endpoint HTTPS của bạn (ví dụ: https://yourapp.com/webhooks/pdfsimple).
3. Chọn các sự kiện bạn muốn nhận (ví dụ: job.completed, job.failed).
4. Nhấp Tạo. Một webhook secret duy nhất được hiển thị — sao chép ngay lập tức, chỉ hiển thị một lần.
5. Lưu secret an toàn trong biến môi trường của ứng dụng.

Sự kiện webhook

• job.completed — tác vụ xử lý PDF hoàn tất thành công. Payload bao gồm ID tác vụ, URL tệp đầu ra và metadata.
• job.failed — tác vụ gặp lỗi. Payload bao gồm thông báo lỗi.

Xác minh chữ ký webhook

Mỗi yêu cầu webhook có header X-PDFSimple-Signature chứa chữ ký HMAC-SHA256 của nội dung yêu cầu thô, được tính bằng webhook secret của bạn. Luôn xác minh chữ ký này trước khi xử lý payload.

const crypto = require('crypto');

function verifySignature(rawBody, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Thử lại và đảm bảo giao nhận

Nếu endpoint của bạn không trả về phản hồi 2xx trong vòng 30 giây, PDFSimple sẽ thử lại với back-off theo cấp số nhân, tối đa 5 lần trong 30 ngày. Sự kiện webhook được lưu trong 30 ngày.