Using Webhooks in a TypeScript Golem Agent

Overview

Golem webhooks let an agent generate a public URL that, when POSTed to by an external system, delivers the request body to the agent. Under the hood, a webhook is backed by a Golem promise. Creation does not suspend the agent. For durable agents awaiting a callback, suspension can occur after the suspension policy delay when all active work permits it. Suspension frees guest execution resources; persisted state and other resources remain.

This is useful for:

• Integrating with webhook-driven APIs (payment gateways, CI/CD, GitHub, Stripe, etc.)
• Receiving asynchronous callbacks from external services
• Building event-driven workflows where an external system notifies the agent

Prerequisites

The agent type must be deployed via an HTTP API mount (http.mount(...) on defineAgent(...) and an httpApi deployment in golem.yaml). Without a mount, webhooks cannot be created.

Related Guides

API

All functions/classes are in @golemcloud/golem-ts-sdk:

Imports

import { createWebhook } from '@golemcloud/golem-ts-sdk';

Webhook URL Structure

Webhook URLs have the form:

https://<domain>/<prefix>/<suffix>/<id>

• <domain> — the domain where the HTTP API is deployed
• <prefix> — defaults to /webhooks, customizable via webhookUrl in the httpApi deployment section of golem.yaml:

  httpApi:
    deployments:
      local:
      - subdomain: my-app  # resolves to my-app.localhost:9006 by default
        webhookUrl: "/my-custom-webhooks/"
        agents:
          OrderAgent: {}

• <suffix> — defaults to the agent type name in kebab-case (e.g., OrderAgent → order-agent), customizable via webhookSuffix
• <id> — a unique identifier for the specific webhook instance

Webhook Suffix

You can configure a webhookSuffix in the mount options of http.mount(...) to override the default kebab-case agent name in the webhook URL:

export const OrderAgent = defineAgent({
  name: 'OrderAgent',
  id: { id: z.string() },
  http: http.mount('/api/orders/{id}', { webhookSuffix: '/workflow-hooks' }),
  methods: { /* ... */ },
});

Only system variables such as {agent-type} and {agent-version} are supported in webhookSuffix, not constructor parameters such as {name}:

http: http.mount('/api/events/{name}', { webhookSuffix: '/{agent-type}/callbacks/{agent-version}' }),

Usage Pattern

1. Create a Webhook, Share the URL, and Await the Callback

const webhook = createWebhook();
const url = webhook.getUrl();
 
// Share `url` with an external service (e.g., register it as a callback URL)
// Awaiting can suspend the durable agent after the suspension policy delay
 
const payload = await webhook;

2. Decode the Payload as JSON

type PaymentEvent = { status: string; amount: number };
 
const webhook = createWebhook();
// ... share webhook.getUrl() ...
const payload = await webhook;
const event = payload.json<PaymentEvent>();

3. Use Raw Bytes

const webhook = createWebhook();
// ... share webhook.getUrl() ...
const payload = await webhook;
const raw: Uint8Array = payload.bytes();

Complete Example

import { z } from 'zod';
import { defineAgent, method, http, createWebhook } from '@golemcloud/golem-ts-sdk';
 
type WebhookEvent = { eventType: string; data: string };
 
export const IntegrationAgent = defineAgent({
  name: 'IntegrationAgent',
  id: { name: z.string() },
  http: http.mount('/integrations/{name}'),
  methods: {
    registerAndWait: method({ input: {}, returns: z.string(), http: http.post('/register') }),
    getLastEvent: method({ input: {}, returns: z.string(), http: http.get('/last-event') }),
  },
});
 
export const IntegrationAgentImpl = IntegrationAgent.implement({
  init: () => ({ lastEvent: '' }),
  methods: {
    async registerAndWait() {
      // 1. Create a webhook
      const webhook = createWebhook();
      const url = webhook.getUrl();
 
      // 2. In a real scenario, you would register `url` with an external service here.
      //    For this example, the URL is created so the caller can POST to it.
      //    Awaiting can suspend the durable agent after the suspension policy delay.
 
      // 3. Wait for the external POST
      const payload = await webhook;
      const event = payload.json<WebhookEvent>();
 
      this.lastEvent = `${event.eventType}: ${event.data}`;
      return this.lastEvent;
    },
    getLastEvent() {
      return this.lastEvent;
    },
  },
});

Key Constraints

• The agent must have an HTTP mount (http.mount(...) on defineAgent(...)) and be deployed via httpApi in golem.yaml
• Completion is first-write-wins: duplicate POSTs return HTTP 204 without replacing the first payload; completion does not immediately invalidate the URL
• Only POST requests to the webhook URL will complete the promise
• WebhookHandler implements PromiseLike, so use await to wait for the callback
• A durable agent can suspend after the suspension policy delay while waiting — it survives failures, restarts, and updates