Using Webhooks in a Scala Golem Agent

Overview

Golem webhooks let an agent generate a temporary 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 — the agent is durably suspended while waiting for the callback, consuming no resources.

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 (mount = "/..." on @agentDefinition and an httpApi deployment in golem.yaml). Without a mount, webhooks cannot be created.

Guide	Description
`golem-add-http-endpoint-scala`	Setting up the HTTP mount and endpoint annotations required before using webhooks
`golem-configure-api-domain`	Configuring `httpApi` in `golem.yaml`, including `subdomain` versus `domain`
`golem-wait-for-external-input-scala`	Lower-level promise API if you need more control than webhooks provide

API

All functions are on the golem.HostApi object:

Function / Type	Description
`HostApi.createWebhook()`	Creates a webhook (promise + public URL) and returns a `WebhookHandler`
`WebhookHandler.url`	The public URL to share with external systems
`WebhookHandler.await()`	Awaits the webhook POST payload asynchronously (`Future[WebhookRequestPayload]`)
`WebhookRequestPayload.json[A]()`	Decodes the POST body as JSON (requires implicit `Schema[A]`)
`WebhookRequestPayload.bytes`	Returns the raw POST body as `Array[Byte]`

Imports


import golem.HostApi
import golem.HostApi.WebhookRequestPayload
import scala.concurrent.Future
import scala.scalajs.concurrent.JSExecutionContext.Implicits.queue

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 on the @agentDefinition annotation to override the default kebab-case agent name in the webhook URL:


@agentDefinition(mount = "/api/orders/{id}", webhookSuffix = "/workflow-hooks")
trait OrderAgent extends BaseAgent {
  class Id(val id: String)
  // ...
}

Path variables in {braces} are also supported in webhookSuffix:


@agentDefinition(mount = "/api/events/{name}", webhookSuffix = "/{agent-type}/callbacks/{name}")

Usage Pattern


val webhook = HostApi.createWebhook()
val url = webhook.url
 
// Share `url` with an external service (e.g., register it as a callback URL)
// The agent is durably suspended here until the external service POSTs to the URL
 
val payload: Future[WebhookRequestPayload] = webhook.await()

2. Create a Webhook and Await Asynchronously


import scala.concurrent.Future
import scala.scalajs.concurrent.JSExecutionContext.Implicits.queue
 
val webhook = HostApi.createWebhook()
val url = webhook.url
// ... share url ...
 
val result: Future[WebhookRequestPayload] = webhook.await()
val bytes: Future[Array[Byte]] = result.map(_.bytes)

3. Decode the Payload as JSON


import zio.blocks.schema.Schema
 
case class PaymentEvent(status: String, amount: Long) derives Schema
 
val webhook = HostApi.createWebhook()
// ... share webhook.url ...
val event: Future[PaymentEvent] = webhook.await().map(_.json[PaymentEvent]())

4. Use Raw Bytes


val webhook = HostApi.createWebhook()
// ... share webhook.url ...
val raw: Future[Array[Byte]] = webhook.await().map(_.bytes)

Complete Example


import golem.*
import golem.runtime.annotations.{agentDefinition, agentImplementation, endpoint}
import zio.blocks.schema.Schema
 
import scala.concurrent.Future
import scala.scalajs.concurrent.JSExecutionContext.Implicits.queue
 
case class WebhookEvent(eventType: String, data: String) derives Schema
 
@agentDefinition(mount = "/integrations/{name}")
trait IntegrationAgent extends BaseAgent {
  class Id(val name: String)
 
  @endpoint(method = "POST", path = "/register")
  def registerAndWait(): Future[String]
 
  @endpoint(method = "GET", path = "/last-event")
  def getLastEvent(): String
}
 
@agentImplementation()
class IntegrationAgentImpl(private val name: String) extends IntegrationAgent {
  private var lastEvent: String = ""
 
  override def registerAndWait(): Future[String] = {
    // 1. Create a webhook
    val webhook = HostApi.createWebhook()
    val url = webhook.url
 
    // Publish the URL before waiting (replace with your callback registration).
    println(s"Webhook for $name: $url")
 
    // 3. Wait for the external POST
    webhook.await().map { payload =>
      val event = payload.json[WebhookEvent]()
      lastEvent = s"${event.eventType}: ${event.data}"
      lastEvent
    }
  }
 
  override def getLastEvent(): String = lastEvent
}

Key Constraints

The agent must have an HTTP mount (mount = "..." on @agentDefinition) and be deployed via httpApi in golem.yaml
The webhook URL is a one-time-use URL — once POSTed to, the promise is completed and the URL becomes invalid
Only POST requests to the webhook URL will complete the promise
Return the Future from await() (or a map/flatMap of it) from the agent method; do not block or detach the wait
The agent is durably suspended while waiting — it survives failures, restarts, and updates
JSON decoding requires an implicit zio.blocks.schema.Schema[A] instance (use derives Schema in Scala 3)