Webhooks Framework - Orchestration

Webhooks Framework - Core Orchestration

Production-grade webhook orchestration for Odoo.

Key Features

• Unified handler model with clear inbound/outbound separation.
• Rule-driven execution or Python callbacks for advanced logic.
• Queue-backed job definitions and async execution primitives.
• Security groups and access rules for webhook administration.
• Stable primitives for connector-backed integrations.

Usage

1. Install this addon alongside bwt_webhooks_inbound and/or
2. Go to Webhooks > Handlers and create a handler for each flow.
3. Choose an execution mode:

Looking for turnkey integrations? Pair this framework with premium connector addons (e.g., Stripe) to launch faster.

Operator Guide

Webhooks Core - Operator Guide

This guide covers the shared foundation of the webhook framework: installing the addon stack, assigning access roles, and creating handler records that both the inbound and outbound gateway addons depend on.

Prerequisites

Install the following addons in order:

1. queue_job - background job execution engine (OCA connector queue).
2. bwt_webhooks_core - shared handler registry and services.
3. bwt_webhooks_inbound (optional) - inbound endpoint gateway.
4. bwt_webhooks_outbound (optional) - outbound delivery engine.

Confirm the queue_job worker process is active on the server before routing live traffic through any endpoint.

Access Roles

Navigate to Settings -> Users & Companies -> Users, open a user record, and locate the Webhooks privilege under the access rights tab.

• Operator - view events, deliveries, and audit records; trigger reprocess and dead-letter actions on individual records.
• Administrator - full read/write on all webhook configuration (handlers, endpoints, rules, signature parts); implies Operator.

Odoo system administrators receive the Administrator role automatically.

Creating a Handler

A handler defines how inbound events or outbound deliveries are processed. It is the shared execution definition consumed by both gateway addons.

Go to Webhooks -> Handlers -> New and fill in:

• Name - human-readable label.
• Code - stable, unique technical identifier (lowercase slug; no spaces).
• Direction - Inbound for events, Outbound for deliveries.
• Execution Mode - choose one:

• Model Driven - configure rule rows directly on the handler form; no Python code required.
• Python Callback - the framework calls a specific method on a specific Odoo model at processing time; requires Python Model and Python Method to be set.

• Company - defaults to the current company.

Save the handler. It is now available to attach to inbound endpoints or outbound endpoint configurations.

Python Callback Setup

When Python Callback is selected:

1. Set Python Model to the technical model name (e.g. sale.order).
2. Set Python Method to the method that will be called (e.g. handle_webhook_event).

Both fields are required; the handler form enforces this before saving.

Archiving Handlers

Archived handlers remain visible in historical audit records but are no longer selectable for new work. Use Action -> Archive from the handler list or form.

Troubleshooting Checklist

• Handler not selectable on an inbound endpoint: verify Direction is set to Inbound.
• Handler not selectable on an outbound endpoint: verify Direction is set to Outbound.
• Python callback raises "method not found": confirm the addon that defines the model is installed and the method name is spelled correctly.
• Jobs are not processing: check that the queue_job worker is running and that no job channel is paused or at capacity.
• Company mismatch errors: the handler, endpoint, and all target records must share the same company.

Developer Guide

Webhooks Core - Developer Guide

This guide covers the core data model, handler execution contract, and service layer. It is the foundation for understanding both the inbound and outbound gateway addons.

Data Model

The core addon defines one primary model:

• bwt.webhook.handler - execution definition shared by both gateway addons. Carries direction, execution mode, and optional Python callback pointers.

The gateway addons extend the graph with these models:

• bwt.webhook.inbound.endpoint - public HTTP receiver (inbound addon).
• bwt.webhook.inbound.event - audit record for each received request.
• bwt.webhook.inbound.handler.rule - declarative rule row on a handler.
• bwt.webhook.outbound.endpoint - target HTTP configuration (outbound addon).
• bwt.webhook.outbound.delivery - queued outbound request snapshot.
• bwt.webhook.outbound.delivery.attempt - per-attempt HTTP execution log.

Handler Execution Modes

Model Driven

Rules on the handler are evaluated in ascending sequence order. Each rule carries:

• Conditions - zero or more field-path comparisons against the event or delivery payload; all conditions must pass for the rule to fire.
• Action - one of done, dead_letter, retry, create_record, update_record, upsert_record.
• Assignments - field path -> value mappings written to the target record on create/update/upsert actions.
• Lookup Keys - field path -> value mappings that locate the existing record for update_record and upsert_record.

The first matching rule wins. If no rule matches, the event or delivery is marked done by default.

Python Callback

Inbound callback signature

def handle_inbound_event(self, event):
    payload = event.get_payload()
    # ... your logic ...
    return event.webhook_done()

Outbound callback signature

def handle_outbound_delivery(self, delivery):
    # ... your logic ...
    return delivery._build_outbound_delivery_result(outcome="send")

Returning None from either callback produces a framework-level dead_letter. Use the helper methods on the event or delivery record to return well-formed results: webhook_done(), webhook_dead_letter(), webhook_retry(seconds=N).

Service Layer

bwt_webhooks_core ships pure-Python service modules that the ORM models delegate to. These can be imported and tested without the ORM:

• services/signature.py - HMAC computation and constant-time verification. Algorithms: sha1, sha256, sha512. Encodings: hex, base64.
• services/transport.py - translates OutboundRequest value objects to requests.request kwargs. Handles json, form_urlencoded, and multipart body modes.
• services/identity.py - delivery identity and replay identity resolution, keyed by a configurable header or payload path.
• services/conditions.py - condition evaluation engine used by model-driven rule processing.
• services/value_objects.py - InboundMetadata, OutboundRequest, and HandlerOutcome data classes that keep the processing pipeline explicit.

Exceptions

All framework exceptions live in bwt_webhooks_core.exceptions:

• WebhookValidationError - base class.
• WebhookSignatureValidationError - HMAC mismatch.
• WebhookFreshnessValidationError - timestamp outside the allowed window.
• WebhookPayloadValidationError - unexpected payload shape.
• WebhookProcessingConfigurationError - misconfigured handler or endpoint.

Extending the Framework

To add a custom processing step:

1. Create a model with a method matching the callback contract above.
2. Create a bwt.webhook.handler record pointing to that model and method via Webhooks -> Handlers.
3. Attach the handler to an inbound endpoint or outbound endpoint record.

To expose a new value in model-driven rule assignments, extend bwt.webhook.inbound.event or bwt.webhook.outbound.delivery with a stored field and make it accessible via the value-extraction path used in assignments.

No core file edits are required; the framework is designed to be extended through standard Odoo model inheritance and configuration records.