Webhooks and Executions

Trigger workflows by webhook, stream activity, and deliver signed execution events to external systems.

B3OS has two webhook directions:

DirectionPurpose
Incoming workflow webhooksExternal systems start a workflow run
Execution hooksB3OS sends run and node lifecycle events to your external system

Incoming Webhooks

Incoming webhooks are useful when an external service can send HTTP events but does not need a dedicated B3OS trigger.

Start a workflow from an external system 
bash
curl -X POST "https://api.b3os.org/v1/webhooks/YOUR_WORKFLOW_SECRET" \  -H "Content-Type: application/json" \  -d '{"event":"payment.created","amount":"42.00","asset":"USDC"}'

The workflow can reference the payload with expressions:

json
{  "event": "{{$trigger.body.event}}",  "amount": "{{$trigger.body.amount}}",  "asset": "{{$trigger.body.asset}}"}

Execution Hooks

Execution hooks send event notifications when workflow runs or node executions change state. Use them to sync B3OS into your own observability, audit, billing, support, or orchestration systems.

Execution hook path
eventsigned POST2xx ackasync processingretry or replay B3OS execution Run and node lifecycle events Hook dispatcher Event filters, signing, delivery attempts Your endpoint Verify signature and enqueue work Delivery record Acknowledgement, retry state, replay history Downstream systems Audit, billing, support, orchestration

Activity Streams

StreamUse
Run streamFollow one run as nodes execute
Activity streamFollow workflow or organization activity
Execution streamFollow node-level execution detail

Delivery Design

1

Create a hook endpoint

Accept signed JSON POSTs, respond quickly, and process heavy work asynchronously.

2

Verify signatures

Treat the hook secret as a credential and verify signatures before trusting events.

3

Use idempotency

Store event IDs or run/execution IDs so retries do not create duplicate side effects.

4

Handle retries

Return a 2xx only after accepting the event. Non-2xx responses can be retried.

Retry is delivery recovery for an event that failed to reach your endpoint. Replay is deliberate redelivery for backfill, debugging, or audit.

Security Notes

SurfaceRecommendation
Incoming workflow webhookTreat the URL or secret as credential material
Execution hook destinationUse HTTPS and verify signatures
Hook payloadAvoid assuming every field is present; handle schema evolution
Side effectsMake handlers idempotent
Private networksDo not route hooks to private or link-local addresses
Ask a question... ⌘I