golem-add-webhook-scala

Call HostApi.createWebhook() to get a WebhookHandler, share its url with the external service, then call awaitBlocking() or await() to receive the POST payload. The agent is durably suspended while waiting and consumes no resources.

Use payload.json[A]() on the WebhookRequestPayload, which requires an implicit zio.blocks.schema.Schema[A] instance. In Scala 3, derive it with `case class MyEvent(...) derives Schema`. Raw bytes are available via payload.bytes.

Webhooks require the agent to have an HTTP mount (mount = "..." on @agentDefinition) and an httpApi deployment in golem.yaml. Also note webhook URLs are one-time-use and only accept POST requests; after the first POST the promise completes and the URL becomes invalid.

Yes. Set webhookUrl in the httpApi deployment section of golem.yaml to change the prefix (default /webhooks), and set webhookSuffix on @agentDefinition to override the default kebab-case agent name. Path variables in braces are supported in webhookSuffix.

await() returns a Future[WebhookRequestPayload] for asynchronous, non-blocking code, while awaitBlocking() blocks the current execution until the POST arrives and returns the payload directly. Use awaitBlocking in synchronous endpoints and await in Future-based flows.