Network Integration

The Publisher as a Microservice

The Publisher software is an internal service in your stack. Treat it the same way you would any other microservice — your backend communicates with it via HTTP API calls over your internal network.

It is not a user-facing service. It uses simple service-level API tokens for authentication rather than user-scoped auth mechanisms like OAuth or session cookies. Your backend services authenticate to it using a Bearer token, the same way they might authenticate to an internal database API or message queue.

Architecture

The Publisher software communicates in two directions:

• Outbound to K42 Platform — The Publisher software initiates connections to the K42 Platform to sync deal configurations, publish transaction identifiers, and submit impressions.
• Inbound from K42 Platform — The Platform sends webhook callbacks to both the Publisher software (for internal state updates like cashback processing) and to your backend (for events you subscribe to). These are secured via HMAC signature verification.

End-User Integration

Your end-users — whether on mobile apps, web frontends, or other channels — never communicate with the Publisher software directly. All user-facing interactions flow through your own backend:

This design means:

• You own the user experience — Transform, filter, or enrich responses before presenting them to users.
• You control access — Apply your own authentication, rate limiting, and authorization before proxying to the Publisher software.
• You shape the data — Expose only what your frontend needs, in whatever format your apps expect.
• Security boundary — The Publisher software doesn't need to handle public internet traffic from arbitrary clients.

Integration Patterns

Delivery

A user requests available offers:

1. Your mobile/web app calls your backend (e.g. GET /api/offers)
2. Your backend calls POST /publisher.v1/delivery/list-eligible with the member ID and ad unit ID
3. Your backend transforms the creative content into your app's format
4. Your backend returns the response to the user's device

Transaction Ingestion

A card transaction occurs:

1. Your payment processing system detects a card authorization
2. Your backend calls POST /publisher.v1/transaction/ingest with the transaction details
3. This is entirely server-side — no user involvement

Clipping a Deal

A user saves a deal:

1. User taps "Save" in your app
2. Your app calls your backend (e.g. POST /api/offers/:id/clip)
3. Your backend calls POST /publisher.v1/wallet.clip/save
4. Your backend returns confirmation to the app

Recording Impressions

A creative is displayed to a user:

1. Your frontend renders a deal creative
2. Your backend (or a background worker) calls POST /publisher.v1/impression/record
3. This can happen synchronously on display or asynchronously in batches

Network Requirements

Direction	From	To	Purpose
Internal	Your backend	Publisher software	API calls (all endpoints)
Outbound	Publisher software	K42 Platform	Sync, transaction publishing, impressions
Inbound	K42 Platform	Publisher software	Webhook callbacks (signature-verified)

The Publisher software does not require inbound access from arbitrary internet clients. Only the K42 Platform needs to reach it for webhook delivery.