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.

For testing purposes, you can setup a temporary webhook URL using https://webhook.site

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 task (complete, failed, 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 'beam-task-status: COMPLETE' \
 -d $'response=example+response'