Tổng quan
Tích hợp Webhook cho phép bạn nhận dữ liệu bài viết từ GroMach và xử lý nó trong hệ thống backend của riêng bạn. Khi bạn xuất bản một bài viết, GroMach sẽ gửi yêu cầu POST đến endpoint bạn đã cấu hình với nội dung bài viết.
Bước 1: Thiết lập Webhook Endpoint
Tạo một endpoint HTTPS trên máy chủ của bạn để nhận các yêu cầu webhook. Endpoint phải:
- Chấp nhận yêu cầu POST: Tất cả dữ liệu webhook được gửi qua POST
- Sử dụng HTTPS: Vì lý do bảo mật, chỉ hỗ trợ URL HTTPS
- Trả về mã trạng thái 2xx: Trả về mã trạng thái thành công để xác nhận đã nhận
Bước 2: Triển khai Xác minh Chữ ký
GroMach ký tất cả các yêu cầu webhook bằng HMAC-SHA256. Bạn nên xác minh chữ ký này để đảm bảo các yêu cầu là xác thực.
Mỗi yêu cầu bao gồm các header sau:
- x-webhook-signature: Chữ ký HMAC-SHA256 của request body
- x-webhook-timestamp: Dấu thời gian ISO 8601 của thời điểm yêu cầu được gửi
- Content-Type: application/json
Dưới đây là ví dụ về xác minh chữ ký trong Node.js:
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
const computedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature, 'hex'),
Buffer.from(computedSignature, 'hex')
);
}
// In your endpoint handler:
app.post('/webhook', (req, res) => {
const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);
if (!verifySignature(payload, signature, YOUR_SECRET_KEY)) {
return res.status(401).json({ error: 'Invalid signature' });
}
// Process the webhook...
res.json({ success: true });
});Bước 3: Định dạng Webhook Payload
Khi một bài viết được xuất bản, GroMach sẽ gửi payload với cấu trúc sau:
{
"event_type": "publish_articles",
"timestamp": "2024-01-15T10:30:00.000Z",
"data": {
"articles": [
{
"id": "article-uuid-123",
"slug": "my-article-slug",
"title": "Article Title",
"excerpt": "Brief description of the article...",
"content_format": "markdown",
"content": "# Full article content in markdown...",
"status": "published",
"published_at": "2024-01-15T10:30:00.000Z",
"author_name": "Admin",
"cover_image": "https://example.com/image.jpg",
"meta_title": "SEO Title",
"meta_description": "SEO meta description",
"tags": ["seo", "marketing"]
}
]
}
}Tham chiếu Trường Bài viết
- id: Mã định danh duy nhất cho bài viết
- slug: Mã định danh thân thiện với URL cho bài viết
- title: Tiêu đề bài viết
- excerpt: Mô tả ngắn gọn hoặc tóm tắt
- content_format: Có thể là "markdown" hoặc "html"
- content: Nội dung bài viết đầy đủ
- status: Trạng thái xuất bản (draft, published, archived)
- published_at: Dấu thời gian xuất bản ISO 8601
- author_name: Tên hiển thị của tác giả
- cover_image: URL của ảnh bìa (nếu có)
- meta_title: Tiêu đề SEO cho công cụ tìm kiếm
- meta_description: Mô tả meta SEO
- tags: Mảng các chuỗi thẻ
Bước 4: Cấu hình trong GroMach
Trong trang tích hợp GroMach, điền các thông tin sau:
- Tên (Tùy chọn): Tên thân thiện để nhận diện webhook này
- Webhook URL: URL endpoint HTTPS của bạn (ví dụ: https://your-site.com/api/webhook)
- Secret Key: Chuỗi bí mật được sử dụng để ký yêu cầu (giữ an toàn!)
- Trạng thái Xuất bản: Chọn xem bài viết được gửi dưới dạng "published" hay "draft"
Quan trọng
Giữ Secret Key của bạn an toàn và không bao giờ để lộ nó trong mã phía client. Sử dụng biến môi trường để lưu trữ nó một cách an toàn trên máy chủ của bạn.
Kiểm tra Webhook của bạn
Trước khi tạo tích hợp, bạn có thể kiểm tra kết nối webhook bằng nút "Test Connection". GroMach sẽ gửi một yêu cầu thử nghiệm để xác minh endpoint của bạn được cấu hình đúng.
Yêu cầu Kiểm tra
Để kiểm tra thành công, endpoint của bạn phải:
- 1. Xác minh chữ ký: Sử dụng secret key để xác minh header
X-Webhook-Signature - 2. Trả về phản hồi thành công: Trả về phản hồi JSON với
{ "success": true }
Payload kiểm tra trông như sau:
{
"event_type": "test",
"timestamp": "2024-01-15T10:30:00.000Z",
"data": {
"message": "This is a test webhook from Gromach SEO",
"integration_name": "My Webhook"
}
}Dưới đây là ví dụ đầy đủ về cách endpoint kiểm tra của bạn nên xử lý yêu cầu:
const crypto = require('crypto');
app.post('/webhook', (req, res) => {
const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);
// Step 1: Verify the signature
const computedSignature = crypto
.createHmac('sha256', YOUR_SECRET_KEY)
.update(payload)
.digest('hex');
const isValid = crypto.timingSafeEqual(
Buffer.from(signature, 'hex'),
Buffer.from(computedSignature, 'hex')
);
if (!isValid) {
return res.status(401).json({
success: false,
error: 'Invalid signature'
});
}
// Step 2: Process based on event type
if (req.body.event_type === 'test') {
// Test connection - just return success
return res.json({ success: true });
}
if (req.body.event_type === 'publish_articles') {
// Process articles...
const articles = req.body.data.articles;
// Save to your database, etc.
return res.json({ success: true });
}
res.json({ success: true });
});Tại sao cần xác minh chữ ký
Xác minh chữ ký đảm bảo rằng các yêu cầu webhook thực sự đến từ GroMach và không bị giả mạo. Đây là phương pháp bảo mật tốt nhất giúp bảo vệ endpoint của bạn khỏi các yêu cầu trái phép.
Khắc phục Sự cố
Kiểm tra kết nối thất bại
- • Xác minh URL endpoint của bạn chính xác và sử dụng HTTPS
- • Đảm bảo máy chủ của bạn có thể truy cập từ internet
- • Kiểm tra endpoint của bạn trả về mã trạng thái 2xx
Xác minh chữ ký thất bại
- • Đảm bảo bạn đang sử dụng Secret Key chính xác từ GroMach
- • Xác minh bạn đang băm request body thô, không phải object đã phân tích
- • Sử dụng so sánh an toàn về thời gian để ngăn chặn tấn công timing
Bài viết không xuất hiện
- • Kiểm tra log máy chủ của bạn để tìm lỗi xử lý
- • Xác minh trạng thái bài viết khớp với quy trình làm việc mong đợi của bạn
- • Đảm bảo các thao tác cơ sở dữ liệu của bạn hoàn thành thành công