Developer docs / AI Fabric tutorials

Completion webhooks: get notified when a job finishes

  • Async job
  • Web endpoint
  • Secret

Take it for a spin

The whole program in one file, ready to run.

async_webhook.py
import bladekit

app = bladekit.app("async-webhook", image="fabric/base")

WEBHOOK_SECRET = "whsec_tutorial_demo"     # in prod: inject via a bladekit.Secret
_results = bladekit.Dict.from_name("async-webhook-results", create_if_missing=True)

@app.web_endpoint(path="/job", methods=["POST"], min_replicas=1, max_replicas=2)
def job(item):
    import time
    time.sleep(3)
    return {"doubled": int(item.get("x", 0)) * 2}

# The receiver MUST be public=True: the completion POST carries no AI Fabric token.
@app.web_endpoint(path="/on-done", methods=["POST"], public=True, min_replicas=1, max_replicas=1)
def on_done(item):
    # fabric/base ships the SDK, so verify_webhook checks the HMAC for you.
    try:
        payload = bladekit.verify_webhook(WEBHOOK_SECRET, item.headers or {}, item.body)
        verified = True
    except ValueError:
        payload, verified = (item if isinstance(item, dict) else {}), False
    _results.put(str(payload.get("call_id")),
                 {"verified": verified, "status": str(payload.get("status"))})
    return {"verified": verified}

@app.local_entrypoint()
def main():
    base = "https://async-webhook.apps.run.blade.sh"
    job = bladekit.Function.from_name("async-webhook", "/job").spawn(
        {"x": 21},
        webhook=bladekit.Webhook(url=f"{base}/on-done", secret=WEBHOOK_SECRET))
    print("submitted:", job.call_id, "->", job.get(timeout=60))
    import time; time.sleep(6)          # give the webhook a moment to fire
    print("receiver recorded:", _results.get(job.call_id))

Run it

  1. Deploy: blade deploy async_webhook.py (both the job and the public receiver).
  2. Pass webhook=bladekit.Webhook(url=..., secret=...) to spawn(). When the job goes terminal, AI Fabric POSTs the receiver with Forge-Signature: t=<unix>,v1=<hmac-sha256(secret, "<t>.<body>")>.
  3. Delivery is durable + at-least-once: it survives a control-plane restart and retries with backoff (8 attempts) until your receiver returns 2xx.
  4. Verify the signature before trusting the payload. The snippet does it inline; with SDK ≥ 0.5.2 in your image you can use bladekit.verify_webhook(secret, headers, raw_body) instead.
  5. Omit the secret and AI Fabric generates one, returned once on handle.webhook_secret. The receiver must be public=True (the completion POST is unauthenticated).

Concepts used: Async job, Webhook, Endpoint, Secret

Contact the team

Loading the form…