Task Callbacks

If you supply a callback_url argument to your function decorator, Beam will make a POST request to your server whenever a task finishes running. Callbacks fire for both successful and failed tasks.

Callbacks include the Beam Task ID in the request headers, and the task response URL-encoded in the request body.

​

Registering a callback URL

Callbacks can be added onto Runs, Task Queues, REST APIs, and Scheduled Jobs:

@app.rest_api(callback_url="http://my-server.io")
def handler():
    ...

​

Callback format

Callbacks include three important bits of information:

1. The Task ID, included in the request header as beam-task-id
2. The payload returned from your task, included in the request body as URL-encoded key-value pairs
3. The status of the completed task: COMPLETE, FAILED, or TIMEOUT.

Here’s an example callback request that Beam would make to your server:

 curl -X POST 'https://your-server.io' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -H 'beam-task-id: 9baee474-97d0-490e-829a-72d2aa002153' \
 -H 'x-beam-task-status: COMPLETE' \
 -d $'response=example+response'

​

Request-level callbacks

There are cases where you might want to define a different callback_url for each request to your function.

You can pass callback_url as a payload to anything you’re running on Beam, and we’ll use that as the callback for the request:

curl -X POST \
  --compressed 'https://bos7e.apps.beam.cloud' \
  -H 'Authorization: [YOUR_AUTH_TOKEN]' \
  -H 'Content-Type: application/json' \
  -d '{"callback_url": "https://webhook.site/341d3777-cdd0-4c7e-82cb-dcc06ea4f774"}'

If you want to access the callback_url in your handler, it’s passed in the inputs argument:

from beam import App, Runtime

app = App(name="my-app", runtime=Runtime())


@app.rest_api()
def run(**inputs):
    # Callback URL can be accessed through input args
    print(f'This is the callback URL: {inputs["callback_url"]}')