> ## Documentation Index
> Fetch the complete documentation index at: https://docs.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

**Execution hook delivery**

**Workflow run**
  **Execution hook**
  **Your receiver**
  **Queue or log**
  **Retry / replay**
  **event**
  **signed POST**
  **2xx after enqueue**
  **failed or manual redelivery**
  **same validation path**

## 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

```javascript node.js
import 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();
});

````

```python python
import hmac
import hashlib
import json
import os
from flask import Flask, request, abort

app = 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)
````

**Header names can vary by hook version**

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.

```sql
create 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        |

**Do not trust unsigned payloads**

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.

## Related Pages

**[Webhooks and executions](/platform/webhooks-executions)**

Conceptual overview of incoming webhooks, execution hooks, and streams.
  **[Security](/platform/security)**

Credential, signature, public route, and workflow safety guidance.