Webhooks

Golem webhooks are built on top of Golem Promises. They let an agent generate a temporary public URL that, when POSTed to by an external system, delivers the request body to the agent. The agent is durably suspended without consuming active compute while it waits. Each URL completes one promise; treat it as a secret, not as a recurring endpoint.

Webhooks are useful for:

Integrating with webhook-driven APIs such as payment gateways, CI/CD systems, GitHub, and Stripe
Receiving async callbacks from external services
Building event-driven workflows where agents react to external events

Webhooks use Golem Promises under the hood. See the Promises page to learn more about the underlying mechanism.

Prerequisites

To use webhooks, your agent must:

Have an HTTP mount defined in its agent annotations
Be deployed via the httpApi section in golem.yaml

Creating a webhook

TypeScript

To create a webhook, call createWebhook. The returned object provides the public URL and can be awaited to receive the incoming payload:


import { createWebhook } from "@golemcloud/golem-ts-sdk"
 
type MyEvent = {
  action: string
  resourceId: string
}
 
async function waitForCallback(): Promise<MyEvent> {
  const webhook = createWebhook()
  const url: string = webhook.getUrl()
  // Send `url` to the external system to POST to
  const payload = await webhook
  const result: MyEvent = payload.json()
  return result
}

Effect TypeScript

Webhook.create returns an Effect that allocates the webhook handle. Await handle.await and decode JSON through an Effect Schema:


import { Effect, Schema } from "effect"
import { Webhook } from "@golemcloud/effect-golem"
 
const MyEvent = Schema.Struct({
  action: Schema.String,
  resourceId: Schema.String,
})
 
const waitForCallback = Effect.gen(function* () {
  const handle = yield* Webhook.create
  const url = handle.url
  // Send `url` to the external system to POST to
  const payload = yield* handle.await
  return yield* payload.decode(MyEvent)
})

Rust

To create a webhook, call create_webhook. The returned object provides the public URL and can be awaited to receive the incoming request:


use golem_rust::create_webhook;
use serde::Deserialize;
 
#[derive(Deserialize)]
struct MyEvent {
    action: String,
    resource_id: String,
}
 
async fn wait_for_callback() -> MyEvent {
    let webhook = create_webhook().expect("failed to create webhook");
    let url: String = webhook.url().to_owned();
    // Send `url` to the external system to POST to
    let request = webhook.await;
    let data: MyEvent = request.json().unwrap();
    data
}

Scala

To create a webhook, call HostApi.createWebhook. The returned object provides the public URL and can be awaited to receive the incoming payload:


import golem.HostApi
import zio.blocks.schema.Schema
 
import scala.concurrent.Future
import scala.scalajs.concurrent.JSExecutionContext.Implicits.queue
 
final case class MyEvent(action: String, resourceId: String) derives Schema
 
def waitForCallback(): Future[MyEvent] =
  val webhook = HostApi.createWebhook()
  val url: String = webhook.url
  // Send `url` to the external system to POST to
  webhook.await().map { payload =>
    val event = payload.json[MyEvent]()
    event
  }

MoonBit

Assuming the golemcloud/golem_sdk/webhook package is imported as @webhook, call create to create a webhook and wait to await the incoming payload:


async fn wait_for_callback() -> String {
  let webhook = @webhook.create()
  let url = webhook.url()
  // Send `url` to the external system to POST to
  let payload = webhook.wait()
  let text = payload.text()
  text
}

Webhook URL structure

When a webhook is created, Golem generates a URL with the following format:


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

<domain> — the domain of the HTTP API deployment
<prefix> — defaults to /webhooks, customizable via the webhookUrl field in the httpApi deployment configuration in golem.yaml
<suffix> — defaults to the agent type name in kebab-case (e.g., my-webhook-agent), customizable via webhookSuffix in agent annotations
<id> — a unique identifier for this particular webhook instance

Customizing the webhook URL

You can customize the webhook URL suffix using the webhookSuffix annotation on your agent:

TypeScript

In the TypeScript SDK the suffix is passed as the webhookSuffix option of http.mount(...) on defineAgent(...):


import { z } from "zod"
import { defineAgent, method, http } from "@golemcloud/golem-ts-sdk"
 
export const WorkflowAgent = defineAgent({
  name: "WorkflowAgent",
  id: { id: z.string() },
  http: http.mount("/workflow/{id}", { webhookSuffix: "/workflow-hooks" }),
  methods: {
    // ...
  },
})

Effect TypeScript

Pass webhookSuffix to Http.mount(...):


import { Schema } from "effect"
import { defineAgent, Http } from "@golemcloud/effect-golem"
 
export const WorkflowAgent = defineAgent({
  name: "WorkflowAgent",
  id: { id: Schema.String },
  http: Http.mount("/workflow/{id}", {
    webhookSuffix: "/workflow-hooks",
  }),
  methods: {
    // ...
  },
})

Rust


#[agent_definition(mount = "/workflow/{id}", webhook_suffix = "/workflow-hooks")]

Scala


@agentDefinition(mount = "/workflow/{id}", webhookSuffix = "/workflow-hooks")

MoonBit


#derive.mount("/workflow/{id}")
#derive.mount_webhook("/workflow-hooks")

Calling the webhook

The webhook URL expects a POST request with an arbitrary body. When the external system sends the POST request, the awaiting agent resumes and receives the payload.

All SDKs expose the raw request-body bytes. Text and JSON decoding helpers vary by SDK, as shown in the examples above. Plain TypeScript’s generic json<T>() parses and casts but does not validate T; use a schema validator when the payload is untrusted.

Configuring webhook URL in golem.yaml

To configure the base URL for webhooks and deploy agents with webhook support, use the httpApi section in golem.yaml:


httpApi:
  deployments:
    local:
    - subdomain: my-app  # resolves to my-app.localhost:9006 by default
      webhookUrl: "/my-custom-webhooks/"  # optional path prefix; defaults to /webhooks
      agents:
        WebhookAgent: {}

The webhookUrl field sets the path prefix that Golem uses when generating webhook URLs (defaults to /webhooks). It is combined with the agent’s webhookSuffix and the generated webhook ID to form the full callback URL, for example http://my-app.localhost:9006/my-custom-webhooks/webhook-agent/<id>.