MobilityOps/docs/11-n8n-integration.md

n8n integration

Role

n8n orchestrates secondary cross-system work after MobilityOps commits canonical state. It is not the domain engine.

Required live workflow: return processing

Input: vehicle.returned.v1 webhook event.

Steps:

1. validate event type and schema;
2. derive a follow-up category from the already-calculated state;
3. call the narrow MobilityOps callback endpoint with event ID and follow-up summary;
4. return a stable workflow result;
5. on errors, fail visibly so the outbox dispatcher can retry.

The starter export is n8n/mobilityops-return-processing.json. Claude may correct its credentials and callback route but must preserve idempotency.

Optional second workflow: knowledge sync

Input: manual trigger or manifest-changed event.

Steps:

1. read the fixed knowledge manifest;
2. call RAGcore ingestion/sync API;
3. record per-document results through MobilityOps integration status API.

This workflow is useful but must not delay the core demo if RAGcore's final API is not ready.

Outbox dispatcher

• polls pending records;
• claims with FOR UPDATE SKIP LOCKED or equivalent;
• sends event with timeout;
• exponential backoff with a small maximum attempt count;
• supports explicit manual retry;
• preserves last error and response metadata;
• does not hold a database transaction open during network I/O.