跳到內容
Hashee Docs

Webhook

Webhook 讓你的 Agent 透過 HTTP POST 請求接收事件，而非維持持久的 WebSocket 連接。這非常適合無伺服器部署和雲端函式。

設定

將 Agent 的連接模式配置為 webhook，並提供 Webhook 密鑰：

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

簽章驗證

每次 Webhook 傳送都包含簽章標頭。處理前務必驗證：

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


// 在你的 HTTP 處理函式中：
const isValid = await verifyWebhookSignature(
  webhookSecret,
  request.headers,
  rawBody
);


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


const payload = parseWebhookPayload(rawBody);

簽章演算法

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

簽章是以時間戳記、投遞 ID 和請求本體的串接（以點號連接）計算的。

內建驗證

SDK 的 verifyWebhookSignature 自動檢查：

檢查項目動作
時間戳記超過 5 分鐘拒絕（防重放）
HMAC 不匹配拒絕（被竄改）
重複的 delivery_id拒絕（在滑動視窗內）

事件類型

Webhook 事件是 WebSocket 事件的子集。僅傳送訊息和關係事件：

事件說明
message.new有新訊息傳送給 Agent
relation.established使用者開始使用 Agent
relation.terminated使用者與 Agent 斷開
relation.suspended使用者被創作者暫停
relation.restored使用者被創作者恢復
artifact_response使用者回應了 Artifact

不透過 Webhook 傳送的事件（僅限 WebSocket）：

  • agent.governance — 治理狀態變更
  • reaction.update — 訊息回應表情
  • group.updated — 群組資訊變更
  • artifact.expired — Artifact TTL 過期
  • session.invalidated — 工作階段終止
  • auth.expiring — Token 即將過期通知

重試策略

如果你的端點返回非 2xx 回應，Hashee 會以指數退避策略重試。每次投遞都有一個唯一的 delivery_id 用於去重。

範例：Express 處理函式

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


  // 處理事件
  console.log(`Received: ${payload.type}`);


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

下一步