Golem 1.5 features — Part 2: Webhooks

Introduction

A series of concise posts showcasing Golem 1.5’s new capabilities, releasing end of April 2026. The episodes of this series are short and assume the reader knows what Golem is. Check the other Golem-related posts for more information.

Webhooks

Building on HTTP API mapping from the prior installment, Golem 1.5 introduces webhook creation and awaiting functionality. Webhooks are built on top of Golem Promises, which were available in previous Golem releases as well.

Creating a webhook

const webhook = createWebhook();
const url = webhook.getUrl();

// At this point we can somehow advertise this `url` - return as a result, post to a 3rd party API, etc

const payload = await webhook; // block until someone calls the webhook with a payload
const result: T = payload.json();

let webhook = create_webhook();
let url = webhook.url();

// At this point we can somehow advertise this `url` - return as a result, post to a 3rd party API, etc

let request = webhook.await;
let data: T = request.json().unwrap();

val webhook = HostApi.createWebhook()
val url = webhook.url

// At this point we can somehow advertise this `url` - return as a result, post to a 3rd party API, etc

webhook.await().map { payload =>
  val event = payload.json[T]()
  // ...
}

let webhook = @webhook.create()
let url = webhook.url()

// At this point we can somehow advertise this `url` - return as a result, post to a 3rd party API, etc

let payload = webhook.wait()
let text = payload.text()

Calling the webhook

Webhooks accept POST requests with arbitrary body content, accessible via payload helper methods.

Customizing the webhook URL

Webhook URLs follow this structure:

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

Configure the prefix in the deployment manifest:

httpApi:
  deployments:
    default:
      - domain: example.com
        webhookUrl: "/my-custom-webhooks/"
        agents:
          # ...

Set a custom suffix via mount point configuration across the supported languages:

@agent({
  mount: "/workflow/{id}",
  webhookSuffix: "/workflow-hooks",
})
class Workflow extends BaseAgent {
  // ...
}

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

@agentDefinition(
  mount = "/workflow/{id}",
  webhookSuffix = "/workflow-hooks",
)
trait Workflow extends BaseAgent {
  // ...
}

#derive.agent
#derive.mount("/workflow/{id}")
#derive.mount_webhook_suffix("/workflow-hooks")
pub(all) struct Workflow {
  // ...
}