Wait using callbacks

Callbacks allow workflow executions to wait for another service to make a request to the callback endpoint; that request resumes the execution of the workflow.

With callbacks, you can signal to your workflow that a specified event has occurred, and wait on that event without polling. For example, you can create a workflow that notifies you when a product is back in stock or when an item has shipped; or that waits to allow human interaction such as reviewing an order or validating a translation.

This page shows you how to create a workflow that supports a callback endpoint, and that waits for HTTP requests from external processes to arrive at that endpoint. You can also wait for events using callbacks and Eventarc triggers.

Callbacks require the use of two standard library built-in functions:

• events.create_callback_endpoint—Creates a callback endpoint expecting the specified HTTP method
• events.await_callback—Waits for a callback to be received at the given endpoint

Create an endpoint that receives a callback request

Create a callback endpoint that can receive HTTP requests to arrive at that endpoint.

1. Follow the steps to create a new workflow, or choose an existing workflow to update but don't deploy it yet.
2. In the workflow's definition, add a step to create a callback endpoint:

   YAML

       - create_callback:
           call: events.create_callback_endpoint
           args:
               http_callback_method: "METHOD"
           result: callback_details
       

   JSON

       [
         {
           "create_callback": {
             "call": "events.create_callback_endpoint",
             "args": {
               "http_callback_method": "METHOD"
             },
             "result": "callback_details"
           }
         }
       ]
         

   Replace METHOD with the expected HTTP method, one of GET, HEAD, POST, PUT, DELETE, OPTIONS, or PATCH. The default is POST.

   The result is a map, callback_details, with a url field that stores the URL of the created endpoint.

   The callback endpoint is now ready to receive incoming requests with the specified HTTP method. The URL of the created endpoint can be used to trigger the callback from a process external to the workflow; for example, by passing the URL to a Cloud Run function.

3. In the workflow's definition, add a step to wait for a callback request:

   YAML

       - await_callback:
           call: events.await_callback
           args:
               callback: ${callback_details}
               timeout: TIMEOUT
           result: callback_request
       

   JSON

       [
         {
           "await_callback": {
             "call": "events.await_callback",
             "args": {
               "callback": "${callback_details}",
               "timeout": TIMEOUT
             },
             "result": "callback_request"
           }
         }
       ]
         

   Replace TIMEOUT with the maximum number of seconds that the workflow should wait for a request. The default is 43200 (12 hours). If the time elapses before a request is received, a TimeoutError is raised.

   Note that there is a maximum execution duration. For more information, see the request limit.

   The callback_details map from the earlier create_callback step is passed as an argument.