EPCIS Events — Capture, Query, Subscriptions
EPCIS 2.0 REST and SOAP, live streaming subscriptions, resilient pagination, OpenSearch event store.
This is the EPCIS 2.0 implementation: events come in at /capture, get queried via Named Queries at /query, and stream out to subscribers as they're indexed. It's the movement side of the platform — an item received, a pallet shipped, a sensor reading recorded — and it leans on the Resolver and Masterdata modules for the descriptive side. Every event references identifiers that resolve through them.
Subscriptions deliver live. When an event lands in the index, every active subscription that matches fires immediately — no poll interval, no missed-window debate. The same subscription model serves WebSocket clients and HTTP webhooks; the platform picks the channel from the subscriber's destination URL. Cron-style scheduled subscriptions sit alongside for clients that prefer batch-style delivery (nightly digests, periodic compliance pulls), and they're opt-in.
A few platform-wide disciplines apply here first. Identifiers are stored in GS1 Digital Link form at rest — every comparison, index, and query runs against the Digital Link representation. URN form is rendered on demand for legacy clients but never re-materialised in storage. Event documents stay lean: no embedded masterdata, no epcisHeader.epcisMasterData block, and custom namespaces have to be declared via the GS1-Extensions header to be picked up by validation. Event-hash deduplication runs during capture, so retrying the same document after a network hiccup is safe.
Long-running queries handle disconnections gracefully. A regulator pulling six months of events can drop the connection, reconnect, and resume on the same scroll cursor without restarting the scan.
The event store underneath is OpenSearch by default; an Elasticsearch backend variant is available for deployments standardised on Elasticsearch, and a headless high-volume capture variant replaces the REST front-end with a Kafka stream consumer for ingestion at scale.
Capabilities by edition
| Capability | OSS | Business |
|---|---|---|
EPCIS 2.0 REST /capture | — | ✓ |
EPCIS 2.0 REST /query (Named Queries) | — | ✓ |
| EPCIS 2.0 SOAP binding (legacy) | — | ✓ |
| Hash-based event deduplication | ✓ lib | ✓ |
| Live streaming subscriptions | — | ✓ |
| Scheduled subscriptions | — | ✓ |
| WebSocket delivery | — | ✓ |
| Webhook delivery | — | ✓ |
| Digital Link canonical form at rest, URN on demand | — | ✓ |
| Reliable paginated queries that survive reconnects | — | ✓ |
| OpenSearch event store | — | ✓ |
| Elasticsearch variant | — | ✓ variant |
| High-volume capture variant (headless) | — | ✓ |
REST surface
| Method | Path | Auth | Role | What it does |
|---|---|---|---|---|
POST | /capture | OIDC / API-key | capture | Submit an EPCIS document (JSON-LD or XML) |
GET | /capture/{captureID} | OIDC / API-key | capture | Check capture-job status |
GET | /events | OIDC / API-key | query | List events (paginated) |
GET | /events/{eventID} | OIDC / API-key | query | Get a single event |
POST | /queries/{queryName} | OIDC / API-key | query | Define a Named Query |
GET | /queries/{queryName}/events | OIDC / API-key | query | Execute a Named Query |
POST | /queries/{queryName}/subscriptions | OIDC / API-key | query | Subscribe — streaming or scheduled |
WS | /subscriptions/{id}/stream | cap-token | query | WebSocket delivery channel |
Standard EPCIS 2.0 dispositions, biz-locations, EPCs, biz-steps, read-points and event-types endpoints all sit under /events/... and respect the same auth/role model.
See also
- Architecture → Live events without polling.
- Architecture → Multi-tenant isolation at the data layer — how queries see only the tenant's data.
- Modules → Formats — the validation chain that runs before capture.
- Modules → Integration — S3 backfill on top of the event store.