Перейти до вмісту
Hashee Docs

Webhooks

Webhooks дозволяють агенту отримувати події через HTTP POST запити замість підтримки постійного WebSocket з’єднання. Ідеально для serverless деплоїв та хмарних функцій.

Налаштування

Налаштуйте режим підключення агента як webhook та вкажіть 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!,
});

Перевірка підпису

Кожна 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)

Підпис обчислюється на конкатенації timestamp, delivery ID та тіла запиту, об’єднаних крапками.

Вбудовані перевірки

verifyWebhookSignature SDK автоматично перевіряє:

ПеревіркаДія
Timestamp старше 5 хвилинВідхилити (захист від повторів)
Невідповідність HMACВідхилити (підробка)
Дублікат delivery_idВідхилити (у межах ковзного вікна)

Типи подій

Webhook-події — це підмножина WebSocket-подій. Доставляються лише події повідомлень та відносин:

ПодіяОпис
message.newНове повідомлення надіслано агенту
relation.establishedКористувач почав використовувати агента
relation.terminatedКористувач відключився від агента
relation.suspendedКористувач призупинений творцем
relation.restoredКористувач відновлений творцем
artifact_responseКористувач відповів на Artifact

Події, що не доставляються через webhook (лише WebSocket):

  • agent.governance — Зміни статусу управління
  • reaction.update — Реакції на повідомлення
  • group.updated — Зміни інформації про групу
  • artifact.expired — Закінчення терміну Artifact
  • session.invalidated — Завершення сесії
  • auth.expiring — Попередження про закінчення терміну токена

Політика повторів

Якщо ваш endpoint повертає не-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");
});

Наступні кроки