@OnEndpoint

Expose custom HTTP endpoints for webhooks, APIs, and integrations.

Overview

The @OnEndpoint decorator exposes methods as HTTP endpoints on your agent's Cloud Run service. Use it for webhooks, custom APIs, health checks, and integration points.

Basic Usage

import { HyperfoldAgent, OnEndpoint } from '@hyperfold/actions-sdk';
@HyperfoldAgent({ name: 'custom-agent', type: 'custom' })
export class CustomAgent {
  @OnEndpoint('/health')
  async healthCheck() {
    return {
      status: 'healthy',
      timestamp: new Date().toISOString(),
      version: '1.2.0',
    };
  }
  @OnEndpoint('/metrics')
  async getMetrics() {
    const stats = await this.analytics.getCurrentStats();
    return {
      active_sessions: stats.sessions,
      requests_per_minute: stats.rpm,
      avg_response_time: stats.avgLatency,
    };
  }
  @OnEndpoint('/webhook/shopify')
  async handleShopifyWebhook(request: Request) {
    const event = request.body;
    await this.processShopifyEvent(event);
    return { received: true };
  }
}

Endpoints are accessible at https://<agent-url>/<path>. The agent URL is shown after deployment.

HTTP Methods

Support different HTTP methods for RESTful APIs:

@OnEndpoint('/products')
async listProducts() {
  return await this.catalog.list();
}
@OnEndpoint('/products', { method: 'POST' })
async createProduct(request: Request) {
  return await this.catalog.create(request.body);
}
@OnEndpoint('/products/:id', { method: 'PUT' })
async updateProduct(request: Request) {
  const { id } = request.params;
  return await this.catalog.update(id, request.body);
}
@OnEndpoint('/products/:id', { method: 'DELETE' })
async deleteProduct(request: Request) {
  await this.catalog.delete(request.params.id);
  return { deleted: true };
}
@OnEndpoint('/orders/:id', { methods: ['GET', 'PATCH'] })
async handleOrder(request: Request) {
  const { id } = request.params;
  if (request.method === 'GET') return await this.orders.get(id);
  return await this.orders.update(id, request.body);
}

Request Handling

Access request data including headers, body, and query parameters. Use request.headers, request.body, request.rawBody (for signature verification), request.query, request.params, and request.files for multipart uploads.

Request Object

Property	Type	Description
`method`	string	HTTP method (GET, POST, etc.)
`headers`	object	Request headers
`body`	any	Parsed request body
`rawBody`	Buffer	Raw body for signature verification
`query`	object	Query string parameters
`params`	object	URL path parameters
`files`	File[]	Uploaded files (multipart)

Authentication

Secure endpoints with API key, JWT, or custom auth. Use auth: 'api_key', auth: 'jwt', or auth: 'custom' in the decorator options. Configure auth in the @HyperfoldAgent decorator.

Always authenticate webhook endpoints to prevent unauthorized access. Use signature verification for payment and order webhooks.

Explore built-in tools in Tools Reference.