Webhooks

Webhooks laten je agent gebeurtenissen ontvangen via HTTP POST-verzoeken in plaats van een permanente WebSocket-verbinding te onderhouden. Dit is ideaal voor serverless deployments en cloudfuncties.

Configuratie

Configureer de verbindingsmodus van je agent als webhook en geef een webhook-secret op:

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

Handtekeningverificatie

Elke webhook-bezorging bevat een handtekeningheader. Verifieer deze altijd voordat je de payload verwerkt:

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

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

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

const payload = parseWebhookPayload(rawBody);

Handtekeningalgoritme

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

De handtekening wordt berekend over de aaneenschakeling van het tijdstempel, de bezorg-ID en de verzoekbody, gescheiden door punten.

Ingebouwde validaties

De verifyWebhookSignature van de SDK controleert automatisch:

Controle	Actie
Tijdstempel ouder dan 5 minuten	Weigeren (anti-replay)
HMAC-mismatch	Weigeren (gemanipuleerd)
Dubbele `delivery_id`	Weigeren (binnen schuivend venster)

Gebeurtenistypen

Webhook-gebeurtenissen zijn een subset van WebSocket-gebeurtenissen. Alleen bericht- en relatiegebeurtenissen worden bezorgd:

Gebeurtenis	Beschrijving
`message.new`	Er is een nieuw bericht naar de agent gestuurd
`relation.established`	Een gebruiker is de agent gaan gebruiken
`relation.terminated`	Een gebruiker heeft de verbinding met de agent verbroken
`relation.suspended`	Een gebruiker is geschorst door de maker
`relation.restored`	Een gebruiker is hersteld door de maker
`artifact_response`	Een gebruiker heeft gereageerd op een artifact

Gebeurtenissen die niet via webhook worden bezorgd (alleen WebSocket):

agent.governance — Wijzigingen in governance-status
reaction.update — Berichtreacties
group.updated — Wijzigingen in groepsinformatie
artifact.expired — Verlopen van artifact-TTL
session.invalidated — Beeindiging van sessie
auth.expiring — Token-verloopwaarschuwing

Herhalingbeleid

Als je endpoint een niet-2xx-respons retourneert, herhaalt Hashee met exponential backoff. Elke bezorging heeft een unieke delivery_id voor deduplicatie.

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

  // Process the event
  console.log(`Received: ${payload.type}`);

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

Volgende stappen

Agent-architectuur — Vergelijk verbindingsmodi
WebSocket-gebeurtenissen — Volledige gebeurtenisreferentie
Foutcodes — Referentie voor foutafhandeling