Webhook Fundamentals

Webhook Fundamentals - Cơ Bản Về Webhook

Tổng Quan

Webhook là cơ chế cho phép một ứng dụng gửi thông tin real-time đến ứng dụng khác khi có sự kiện xảy ra. Trong RedAI, Webhook là Trigger phổ biến nhất để khởi động Workflow.

Webhook Là Gì?

Webhook giống như một "callback URL" mà bạn cung cấp cho hệ thống bên ngoài. Khi có event, hệ thống sẽ gửi HTTP request đến URL này.

External System → Event Occurs → HTTP POST → Your Webhook URL → Workflow Triggers

Khi Nào Dùng Webhook?

Use case

Có Webhook

Nhận data từ form

✅

Integration với payment gateway

✅

Nhận notification từ service

✅

Polling data định kỳ

❌ Dùng Schedule

Các Loại Webhook

1. Inbound Webhook (Receive)

Nhận data từ bên ngoài:

  • Payment callback

  • Form submission

  • Third-party notifications

2. Outbound Webhook (Send)

Gửi data đến bên ngoài:

  • Notify external system

  • Trigger other services

Webhook Trong RedAI

Webhook URL Format

https://api.redai.vn/webhook/{workflow_id}

HTTP Methods Supported

Method

Use case

GET

Simple triggers, health checks

POST

Data submission (phổ biến nhất)

PUT

Update operations

DELETE

Delete triggers

Request Format

{
  "headers": {
    "Content-Type": "application/json",
    "X-Signature": "abc123..."
  },
  "body": {
    "event": "order.created",
    "data": {
      "order_id": "12345",
      "amount": 500000
    }
  }
}

Thiết Lập Webhook Node

Bước 1: Thêm Webhook Node

  1. Mở Workflow editor

  2. Kéo Webhook Node vào canvas

  3. Node sẽ hiển thị webhook URL

Bước 2: Cấu Hình Webhook

  • Method: Chọn GET/POST

  • Authentication: Optional API key

  • Response Mode: Sync/Async

Bước 3: Copy URL

Copy webhook URL và cung cấp cho hệ thống bên ngoài.

Bước 4: Test Webhook

  1. Sử dụng Postman hoặc curl

  2. Gửi request đến webhook URL

  3. Kiểm tra Workflow trigger

Webhook Security

HMAC Signature

Verify request đến từ source tin cậy:

// Generate signature
const signature = crypto
  .createHmac('sha256', secret)
  .update(JSON.stringify(body))
  .digest('hex');

// Verify in RedAI
if (signature === request.headers['x-signature']) {
  // Valid request
}

API Key Authentication

Thêm API key vào header:

X-API-Key: your_api_key_here

Best Practices

[!TIP]
Webhook tốt:

  • Always validate incoming data

  • Return 200 OK quickly

  • Log all requests for debugging

  • Implement retry logic

[!WARNING]
Tránh:

  • Expose sensitive data trong URL

  • Không validate signature

  • Slow response causing timeout

Troubleshooting

Vấn đề

Nguyên nhân

Giải pháp

404 Not Found

Sai URL

Kiểm tra workflow active

Timeout

Response chậm

Tăng timeout hoặc async

Invalid Signature

Sai secret

Verify secret config

Các Bước Tiếp Theo