The processing webhook

Driving orders via the API

An optional tenant feature: the moment extraction finishes — before any human review, and regardless of PROCESSED or ATTENTION — AIOTIC POSTs the extracted order to a URL you provide.

Rendering diagram…

Two moments, two payloads: the AI's reading (webhook) and the reviewed order (ERP hand-off).

Contract

POST https://integration.example.com/aiotic/processing
Content-Type: application/json
X-API-KEY: <webhook key you provided>

{ "request_id": "…", "purchase_order": { …PurchaseOrder as in result… } }

Respond 2xx. That is all: delivery is best effort — no retries, no signature, no event type, no status field. If your endpoint is down, the signal is lost (the order itself is not; it is still in AIOTIC).

The body is the PurchaseOrder shape (with quantity_state, customer_item_number, delivery_date_from/to), not the ERP hand-off subset.

What it is good for

• Pre-create a draft in your system so the ERP hand-off is a state change, not a new record.
• Notify a team that an order from customer X arrived.
• Start your own enrichment (price check, stock) in parallel with the human review.
• Statistics: volume per customer, time from arrival to send.

What it is not

• Not the hand-off. The payload is unreviewed. Booking from it means booking the AI's mistakes.
• Not a status feed. It fires once per order. For SENT/CANCELED use the watcher.
• Not guaranteed. Design for a missed call: the watcher (or a nightly list) is the reconciliation.

Receiving it with the SDK

from aiotic.webhooks import ProcessingWebhookReceiver, create_webhook_routers

def on_processed(req):                 # req: ProcessingWebhookRequest
    drafts.create(req.request_id, req.purchase_order)

app.include_router(create_webhook_routers(processing=ProcessingWebhookReceiver(WEBHOOK_KEY, on_processed)))
# → POST /aiotic/processing

build_app() wires this automatically when AIOTIC_WEBHOOK_KEY is set.

Enabling it

A tenant admin sets output → webhook (URL, key, enabled) in the AIOTIC app; the AIOTIC team can do it during onboarding. The mock tenant takes MOCK_WEBHOOK_URL / MOCK_WEBHOOK_KEY or a POST /_mock/config.

Future

Signed, typed, retried event webhooks (order.processed, order.attention, order.sent, …) are proposed. The SDK already contains the signature verifier so your endpoint can adopt them without a rewrite.