Integration Gateway

English · Español

Reusable TypeScript backend for REST APIs, signed webhooks, SOAP/XML, background jobs, retries and enterprise adapters.

Integration Gateway is a clean-room integration starter built around explicit ports, adapters and trust boundaries. It demonstrates how to receive signed events, call REST/SOAP systems, schedule retryable work, preserve dead-letter history and expose low-cardinality operational signals without coupling the core to a specific CRM, ERP, booking engine, payment provider or vendor API.

v1.0.0 is the first stable baseline. All bundled examples and payloads are fictional.

Capabilities

Signed inbound webhooks

• route-scoped raw-body capture;
• timestamped HMAC-SHA256 verification;
• constant-time digest comparison;
• stale/future request rejection;
• mandatory idempotency keys;
• completed-request replay and duplicate-in-progress blocking;
• correlation IDs and audit records.

Outbound REST

• provider-neutral connector port;
• server-configured base URL only;
• relative-path/origin validation and redirects disabled;
• timeout and normalized failure classification;
• bounded exponential backoff and capped Retry-After;
• retries only when the operation has safe/idempotent semantics.

SOAP / XML

• SOAP 1.1 and SOAP 1.2 envelope generation;
• SOAPAction / SOAP 1.2 action transport conventions;
• XML values generated by an XML builder rather than string concatenation;
• custom entity processing disabled;
• normalized SOAP Fault handling;
• fixed server-configured endpoint;
• timeout and maximum response-size enforcement;
• no generic automatic SOAP retries.

Background jobs and dead-letter

• provider-neutral IntegrationJob domain;
• explicit repository and executor ports;
• atomic reference claim before execution;
• queued / running / retry-scheduled / succeeded / dead-letter lifecycle;
• bounded retry budget;
• replay creates a new linked job without mutating the failed record;
• transition history and correlation IDs;
• opt-in polling worker disabled by default;
• process-local low-cardinality reference metrics.

Architecture

                         Integration Gateway

 inbound webhook                                      async / outbound
       |                                                      |
 raw body + HMAC                                      application service
       |                                                      |
 idempotency claim                         +-------------------+------------------+
       |                                   |                   |                  |
       +---------------------------> REST connector       SOAP connector      JobService
                                           |                   |                  |
                                      external REST       external SOAP       JobRepository
                                                                                 |
                                                                            JobExecutor
                                                                                 |
                                                                          retry / dead-letter

Vendor-specific DTOs, credentials, operation names and mappings belong in dedicated adapters/executors. The generic routes and domain models do not contain production customer integrations.

Documentation:

• docs/README.md
• docs/ARCHITECTURE.md
• docs/WEBHOOKS.md
• docs/OUTBOUND-REST.md
• docs/SOAP-XML.md
• docs/JOBS.md
• docs/ADAPTER-GUIDE.md
• docs/DEPLOYMENT.md
• docs/PRODUCTION-CHECKLIST.md

Quick start

Requires Node.js 24.12+ and npm 11.

npm ci
cp .env.example .env.local
npm run dev

Default local URL: http://127.0.0.1:3001.

All external connectors and operational demo surfaces are disabled until explicitly configured. The background worker is disabled by default.

Safe defaults

WEBHOOK_SIGNING_SECRET=
EXPOSE_AUDIT_API=false
OUTBOUND_BASE_URL=
SOAP_ENDPOINT=
JOB_WORKER_ENABLED=false
ENABLE_DEMO_API=false
ENABLE_DEMO_TARGET=false

Production boundary

The repository is a reusable integration foundation, not a turnkey production control plane. The following bundled components are intentionally reference/demo implementations and must be replaced or protected for real workloads:

• in-memory event, webhook-audit, idempotency and job repositories;
• process-local job metrics;
• demo HTTP routes and fictional targets;
• demo job executor;
• unauthenticated demo/audit/job-management surfaces.

A production deployment must add durable shared persistence/queues, atomic multi-worker claims, provider-specific authentication and mapping, secrets management, protected operations APIs, structured observability, rate limits and deployment-specific network controls. Follow docs/PRODUCTION-CHECKLIST.md.

Public/demo routes

Core reference routes:

GET  /health
GET  /ready
POST /v1/integration-events
GET  /v1/integration-events
GET  /v1/integration-events/:id
POST /v1/webhooks/:source/:eventType

Additional audit/demo routes exist only when their explicit configuration flags are enabled. See the documentation before exposing any of them outside local/CI environments.

Quality gate

npm run verify
npm audit --audit-level=high

CI performs:

• public-source safety scan;
• release-consistency checks;
• unit tests;
• strict TypeScript checking;
• production build;
• compiled-server HTTP smoke tests;
• valid/invalid/replayed webhook checks;
• bounded REST retry validation;
• SOAP success/fault validation;
• job retry → success, dead-letter and replay validation;
• high-severity dependency audit.

Version history

Version	Focus
0.1.0	Fastify foundation and integration domain
0.2.0	Signed webhooks, idempotency and audit
0.3.0	Outbound REST, failure classification and retries
0.4.0	SOAP/XML boundary and Fault handling
0.5.0	Jobs, dead-letter, replay and observability
1.0.0	Stable documented reusable baseline

Future work is tracked in ROADMAP.md.

Security, support and contributing

• SECURITY.md
• SUPPORT.md
• CONTRIBUTING.md

License

MIT © 2026 Eduardo Yauri. See LICENSE.