Lewati ke konten
Hashee Docs

Webhook

Webhook cho phép agent nhận sự kiện qua yêu cầu HTTP POST thay vì duy trì kết nối WebSocket liên tục. Lý tưởng cho triển khai serverless và cloud function.

Cài Đặt

Cấu hình chế độ kết nối agent là webhook và cung cấp webhook secret:

const agent = await HasheeAgent.init({
  agentId: process.env.HASHEE_AGENT_ID!,
  token: process.env.HASHEE_AGENT_TOKEN!,
  baseUrl: "https://api.hashee.ai",
  connectionMode: "webhook",
  webhookSecret: process.env.HASHEE_WEBHOOK_SECRET!,
});

Xác Minh Chữ Ký

Mỗi webhook đều kèm header chữ ký. Luôn xác minh trước khi xử lý:

import {
  verifyWebhookSignature,
  parseWebhookPayload,
} from "@hasheeai/agent-sdk-ts";


// Trong HTTP handler:
const isValid = await verifyWebhookSignature(
  webhookSecret,
  request.headers,
  rawBody
);


if (!isValid) {
  return new Response("Unauthorized", { status: 401 });
}


const payload = parseWebhookPayload(rawBody);

Thuật Toán Chữ Ký

HMAC-SHA256(webhook_secret, timestamp + "." + delivery_id + "." + body)

Chữ ký được tính trên chuỗi nối timestamp, delivery ID và body yêu cầu, phân cách bằng dấu chấm.

Kiểm Tra Tích Hợp

verifyWebhookSignature của SDK tự động kiểm tra:

Kiểm traHành động
Timestamp cũ hơn 5 phútTừ chối (chống phát lại)
HMAC không khớpTừ chối (bị giả mạo)
delivery_id trùng lặpTừ chối (trong cửa sổ trượt)

Loại Sự Kiện

Sự kiện webhook là tập con của sự kiện WebSocket. Chỉ sự kiện tin nhắn và quan hệ được gửi:

Sự kiệnMô tả
message.newTin nhắn mới gửi đến agent
relation.establishedNgười dùng bắt đầu sử dụng agent
relation.terminatedNgười dùng ngắt kết nối khỏi agent
relation.suspendedNgười dùng bị người tạo tạm ngừng
relation.restoredNgười dùng được người tạo khôi phục
artifact_responseNgười dùng phản hồi artifact

Sự kiện không gửi qua webhook (chỉ WebSocket):

  • agent.governance — Thay đổi trạng thái quản trị
  • reaction.update — Phản ứng tin nhắn
  • group.updated — Thay đổi thông tin nhóm
  • artifact.expired — Hết hạn TTL artifact
  • session.invalidated — Kết thúc phiên
  • auth.expiring — Cảnh báo token sắp hết hạn

Chính Sách Thử Lại

Nếu endpoint trả về response không phải 2xx, Hashee thử lại với exponential backoff. Mỗi delivery có delivery_id duy nhất để loại trùng.

Ví Dụ: Express Handler

import express from "express";
import {
  verifyWebhookSignature,
  parseWebhookPayload,
} from "@hasheeai/agent-sdk-ts";


const app = express();


app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  const isValid = await verifyWebhookSignature(
    process.env.HASHEE_WEBHOOK_SECRET!,
    req.headers,
    req.body
  );


  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }


  const payload = parseWebhookPayload(req.body);


  // Xử lý sự kiện
  console.log(`Received: ${payload.type}`);


  res.status(200).send("OK");
});

Bước Tiếp Theo