Execution Hooks
Deliver signed B3OS run and execution events to your backend.
Execution hooks send B3OS run and node execution events to your backend. Use them for observability, audit logs, customer notifications, billing sync, support workflows, and downstream orchestration.
Event Model
| Event family | Examples |
|---|---|
| Run lifecycle | Run started, waiting, succeeded, failed, cancelled |
| Node lifecycle | Execution pending, running, succeeded, failed, skipped, waiting, scheduled |
| Delivery lifecycle | Hook delivery attempts, retries, replay, and delivery status |
Hook Receiver Requirements
HTTPS endpoint that accepts signed JSON POST requests from B3OS.
Event types the hook should receive.
Shared secret used to verify delivery signatures. Store it as a backend secret.
Whether B3OS should deliver events to the hook.
Example Receiver
javascriptimport crypto from "node:crypto";import express from "express";const app = express();app.use(express.raw({ type: "application/json" }));app.post("/b3os/hooks", (req, res) => {const signature = req.header("x-b3os-signature");const expected = crypto.createHmac("sha256", process.env.B3OS_WEBHOOK_SECRET).update(req.body).digest("hex");if (signature !== expected) {return res.status(401).send("invalid signature");}const event = JSON.parse(req.body.toString("utf8"));queueEventForProcessing(event);res.status(204).send();});
pythonimport hmacimport hashlibimport jsonimport osfrom flask import Flask, request, abortapp = Flask(__name__)@app.post("/b3os/hooks")def b3os_hooks(): body = request.get_data() expected = hmac.new( os.environ["B3OS_WEBHOOK_SECRET"].encode(), body, hashlib.sha256, ).hexdigest() if request.headers.get("x-b3os-signature") != expected: abort(401) event = json.loads(body.decode("utf-8")) queue_event_for_processing(event) return ("", 204)
Check the API reference and hook configuration response for the exact signature headers your deployment emits.
Idempotency
Execution hook receivers should be idempotent. Store a unique event ID, run ID plus event type, or execution ID plus event type before doing side effects.
sqlcreate table b3os_hook_events ( event_id text primary key, received_at timestamptz not null default now(), payload jsonb not null);
Delivery Behavior
| Behavior | Recommendation |
|---|---|
| 2xx response | Treat as accepted and process asynchronously if work is slow |
| Non-2xx response | B3OS may retry according to delivery policy |
| Timeout | Keep receiver fast and move heavy work to a queue |
| Duplicate event | Use idempotency keys |
| Replay | Handle replayed events the same way as first delivery |
Always verify hook signatures before processing. Do not allow hook events to trigger wallet, payment, or privileged operations without verification and policy checks.
Replay Versus Retry
Retry is automatic delivery recovery after a failed attempt. Replay is intentional redelivery for debugging, audit backfill, or resyncing your external system.