Job callbacks

Give a long-running job an inbox URL and wait for it to call back instead of polling.

Many APIs that do slow work (video rendering, batch inference, transcription, CI pipelines, document processing) accept a callback URL and post to it when they finish. An inbox lets an agent use those callbacks instead of polling.

The pattern#

1. Create an inbox with a lifetime longer than the job could take.
2. Start the job with callback_url (or whatever the API calls it) set to <url>/jobs/<job-id>.
3. Call wait_for_request with path_prefix: "/jobs/<job-id>", and call it again whenever it times out.

{ "inbox_key": "porch_sk_…", "path_prefix": "/jobs/render-42", "timeout_seconds": 300 }

Each call waits up to 5 minutes, and because positions are saved, a callback that lands between calls is returned by the next one.

Several jobs at once#

Give each job its own path. Waiting on /jobs/render-42 never consumes the callback for /jobs/render-43; each filter keeps its own position. To take whichever finishes first, wait with path_prefix: "/jobs/" instead.

Long jobs#

• An inbox lives for at most 7 days (ttl_minutes up to 10080).
• The inbox is deleted after 4 hours without a tool call that uses its key. An agent that waits in a loop keeps it alive naturally; one that comes back later should call get_inbox at least every few hours.
• Each captured request is kept for 4 hours, so read the callback within that window.

Answering the job#

Some APIs expect a particular response to the callback, for example 202 Accepted or a JSON acknowledgement. Set it before starting the job:

{ "inbox_key": "porch_sk_…", "path_prefix": "/jobs/", "status": 202, "body": "{\"received\":true}", "content_type": "application/json" }