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.
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
- Deploy:
blade deploy async_webhook.py(both the job and the public receiver). - Pass
webhook=bladekit.Webhook(url=..., secret=...)tospawn(). When the job goes terminal, AI Fabric POSTs the receiver withForge-Signature: t=<unix>,v1=<hmac-sha256(secret, "<t>.<body>")>. - Delivery is durable + at-least-once: it survives a control-plane restart and retries with backoff (8 attempts) until your receiver returns 2xx.
- 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. - Omit the secret and AI Fabric generates one, returned once on
handle.webhook_secret. The receiver must bepublic=True(the completion POST is unauthenticated).
Concepts used: Async job, Webhook, Endpoint, Secret