API

Documentation Map

• Overview

• Quick Start

• Installation

• Configuration

• Operations

• Troubleshooting

• Release Notes

• Compatibility

• Architecture

• API Reference

• Security

• Integrations

• Capabilities

• Roadmap

• Project Plan

• OSS Inventory

• Channel: latest

• Source repo: JaddaHelpifyr/jhf-wire

API

Webhooks Exposed

Endpoint	Method	Auth	Stability	Purpose
/webhook/clawledger/sepa/submit	POST	INGRESS_AUTH_MODE=network-trust (default) or shared-secret via x-ingress-secret	stable	SEPA submit ingress
/webhook/clawledger/bank/sync	POST	INGRESS_AUTH_MODE=network-trust (default) or shared-secret via x-ingress-secret	stable	bank sync ingress
/webhook/clawledger/invoice/dispatch	POST	INGRESS_AUTH_MODE=network-trust (default) or shared-secret via x-ingress-secret	pilot	invoice dispatch ingress
/webhook/clawledger/tax/submit	POST	INGRESS_AUTH_MODE=network-trust (default) or shared-secret via x-ingress-secret	pilot	tax submit ingress

Ingress Auth Mode

• network-trust keeps backward compatibility and expects trusted internal network placement.
• shared-secret requires x-ingress-secret header on all ingress webhook requests.
• Migration path:
  • keep network-trust during transition
  • configure INGRESS_SHARED_SECRET
  • switch to INGRESS_AUTH_MODE=shared-secret

Example Inbound Payloads

SEPA Submit Ingress Example

Headers:

• Content-Type: application/json
• x-ingress-secret: <shared secret> when INGRESS_AUTH_MODE=shared-secret

Body:

{
  "dispatch_job": "SEPA-BATCH-001",
  "callback": {
    "url": "https://clawledger.example/api/method/clawledger_core.api.callbacks.n8n_job_result"
  },
  "document": {
    "attachments": [
      {
        "kind": "xml",
        "filename": "sepa.xml",
        "content": "<Document/>"
      }
    ]
  }
}

Bank Sync Ingress Example

Headers:

• Content-Type: application/json
• x-ingress-secret: <shared secret> when INGRESS_AUTH_MODE=shared-secret

Body:

{
  "dispatch_job": "BANKSYNC-2026-001",
  "callback": {
    "url": "https://clawledger.example/api/method/clawledger_core.api.callbacks.n8n_job_result"
  },
  "bank_connection_id": 3231708,
  "from_date": "2026-03-01"
}

Invoice Dispatch Ingress Example

Headers:

• Content-Type: application/json
• x-ingress-secret: <shared secret> when INGRESS_AUTH_MODE=shared-secret

Body:

{
  "dispatch_job": "INV-2026-001",
  "recipient": "4012345123484",
  "callback": {
    "url": "https://clawledger.example/api/method/clawledger_core.api.callbacks.n8n_job_result"
  },
  "document": {
    "attachments": [
      {
        "kind": "xml",
        "filename": "xrechnung.xml",
        "content": "<Invoice/>"
      }
    ]
  }
}

Tax Submit Ingress Example

Headers:

• Content-Type: application/json
• x-ingress-secret: <shared secret> when INGRESS_AUTH_MODE=shared-secret

Body:

{
  "dispatch_job": "ELSTER-2026-001",
  "callback": {
    "url": "https://clawledger.example/api/method/clawledger_core.api.callbacks.n8n_job_result"
  },
  "document": {
    "attachments": [
      {
        "kind": "xml",
        "filename": "ustva.xml",
        "content": "<Elster/>"
      }
    ]
  }
}

Callback Emitted

Surface	Method	Auth	Stability	Purpose
callback.url from dispatch payload	POST	X-Signature, X-Idempotency-Key	stable	report job outcome back to Helpifyr Spindle

Callback Examples

Delivered Callback Example

Headers:

• Content-Type: application/json
• X-Signature: <hmac_sha256_hex>
• X-Idempotency-Key: DISPATCH-2026-001

Body:

{
  "dispatch_job": "DISPATCH-2026-001",
  "status": "delivered",
  "status_code": 200,
  "external_reference": "provider-reference",
  "delivery_evidence": {
    "contract_version": "v1",
    "idempotency_key": "DISPATCH-2026-001",
    "callback_attempt": 1,
    "callback_http_code": 200,
    "degraded_delivery_mode": false
  }
}

Error Callback Example

Headers:

• Content-Type: application/json
• X-Signature: <hmac_sha256_hex>
• X-Idempotency-Key: DISPATCH-2026-001

Body:

{
  "dispatch_job": "DISPATCH-2026-001",
  "status": "error",
  "status_code": 502,
  "error_code": "provider_rejected",
  "error_message": "Provider rejected the submission",
  "retryable": false,
  "delivery_evidence": {
    "contract_version": "v1",
    "idempotency_key": "DISPATCH-2026-001",
    "callback_attempt": 5,
    "callback_http_code": 500,
    "degraded_delivery_mode": true
  },
  "support_notification": {
    "notification_kind": "support-case-update",
    "severity": "critical",
    "reply_transport": {
      "mode": "signed-callback",
      "idempotency_key": "DISPATCH-2026-001"
    }
  }
}

Approval Required Callback Example

Headers:

• Content-Type: application/json
• X-Signature: <hmac_sha256_hex>
• X-Idempotency-Key: DISPATCH-2026-001

Body:

{
  "dispatch_job": "DISPATCH-2026-001",
  "status": "approval_required",
  "status_code": 409,
  "reason": "vop_close_match",
  "error_code": "vop_close_match",
  "error_message": "1 of 5 items require operator approval after VoP check",
  "retryable": true,
  "vop_results": [
    {
      "iban": "DE89370400440532013000",
      "party": "Close Test",
      "payment_reference": "E2E-001",
      "vop_status": "CLOSE_MATCH",
      "suggested_name": "Close Test GmbH"
    }
  ],
  "delivery_evidence": {
    "contract_version": "v1",
    "idempotency_key": "DISPATCH-2026-001",
    "callback_attempt": 2,
    "callback_http_code": 409,
    "degraded_delivery_mode": false
  }
}

Health Surfaces

Endpoint	Method	Purpose
${N8N_BASE_URL}/healthz	GET	n8n health
${ERIC_HEALTHCHECK_URL}/health	GET	ERiC service health

Readiness Surface

There is no HTTP readiness endpoint today.

The canonical readiness contract is:

bash scripts/check_runtime_readiness.sh

Combined Status Surface

The current machine-readable combined status view is:

python scripts/export-fabric-metadata.py --pretty

It exposes:

• version
• health surfaces
• readiness classification
• declared capabilities
• standardized connections

Non-HTTP Readiness And Metrics Contracts

• Readiness:
  • bash scripts/check_runtime_readiness.sh
  • bash scripts/check_stack_state.sh
• Metrics:
  • no repo-owned metrics endpoint or metrics CLI contract exists today
  • this remains a documented gap, not an undocumented omission

Example Callback Headers

• Content-Type: application/json
• X-Signature: <hmac_sha256_hex>
• X-Idempotency-Key: <dispatch_job>

Versioning Logic

• no standalone API version namespace exists for jhf-wire
• compatibility is tracked via Git, docs, workflow JSON, and fabric-manifest.json

Contract Regression Coverage

• callback header/body contract and ingress auth guardrails are enforced in:
  • tests/test_workflow_contracts.py
  • scripts/check_workflow_runtime_compat.py
• support delivery/recovery contract and corner cases are enforced in:
  • scripts/validate_support_case_delivery.py
  • scripts/check_support_case_delivery.sh
  • docs/SUPPORT_CASE_DELIVERY_CONTRACT.md

---

License: AGPLv3 Project website: https://helpifyr.com