Перейти к содержимому
Hashee Docs

Webhooks

Webhooks permitem que seu agente receba eventos via requisicoes HTTP POST em vez de manter uma conexao WebSocket persistente. Ideal para implantacoes serverless e cloud functions.

Configuracao

Configure o modo de conexao do seu agente como webhook e forneca um 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!,
});

Verificacao de Assinatura

Cada entrega de webhook inclui um header de assinatura. Sempre verifique antes de processar:

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


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


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


const payload = parseWebhookPayload(rawBody);

Algoritmo de Assinatura

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

A assinatura e calculada sobre a concatenacao do timestamp, delivery ID e corpo da requisicao, unidos por pontos.

Validacoes Integradas

O verifyWebhookSignature do SDK verifica automaticamente:

VerificacaoAcao
Timestamp com mais de 5 minutosRejeitar (anti-replay)
Incompatibilidade de HMACRejeitar (adulterado)
delivery_id duplicadoRejeitar (dentro da janela deslizante)

Tipos de Evento

Eventos de webhook sao um subconjunto de eventos de WebSocket. Apenas eventos de mensagem e relacionamento sao entregues:

EventoDescricao
message.newUma nova mensagem foi enviada ao agente
relation.establishedUm usuario comecou a usar o agente
relation.terminatedUm usuario se desconectou do agente
relation.suspendedUm usuario foi suspenso pelo criador
relation.restoredUm usuario foi restaurado pelo criador
artifact_responseUm usuario respondeu a um artifact

Eventos nao entregues via webhook (apenas WebSocket):

  • agent.governance — Mudancas de status de governanca
  • reaction.update — Reacoes a mensagens
  • group.updated — Mudancas de informacoes do grupo
  • artifact.expired — Expiracao de TTL do artifact
  • session.invalidated — Encerramento de sessao
  • auth.expiring — Aviso de expiracao de token

Politica de Retentativa

Se seu endpoint retornar uma resposta nao-2xx, o Hashee retenta com backoff exponencial. Cada entrega tem um delivery_id unico para deduplicacao.

Exemplo: Handler 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);


  // Processa o evento
  console.log(`Received: ${payload.type}`);


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

Proximos Passos