Outcome Delivery

An outcome is anything IVK Match reports to the game backend asynchronously: a match was formed, a backfill was filled, tickets expired or were removed. The message schema is identical across every sink; see Matchmaking API reference § Outcome schema. What follows is how those outcomes reach the game backend.

Coming soon

Neither sink below is in the current build. Both designs are settled and can be built against. The webhook sink requires an HTTP handler and a shared secret; the WebSocket sink requires a consumer that tracks an offset. Integration work done against either design now carries over unchanged when it ships.

Why the delivery path matters

A formed match is a commitment. By the time an outcome exists, the tickets have already left the pool and those players are no longer matchmaking. If the outcome is lost, those players are stranded on a screen that never advances.

Delivery therefore has to survive a backend that was down for thirty seconds during a deploy and pick up exactly where it left off, without requiring the integration to operate a message broker to receive a match.

Under both sinks an outcome is recorded durably before it is delivered, and is not considered handled until the consumer acknowledges it. A failed webhook or a dropped WebSocket delays delivery; it does not lose it. Durability is handled by IVK Match; the integration only chooses how outcomes arrive.

Chosen per queue

The sink is part of the queue’s configuration, not a game-wide setting. Two queues on the same game can deliver to different endpoints, and delivery can be repointed with a configuration edit rather than a deploy. See Queue Configuration § config.outcomes.

---

Sink comparison

Sink	Delivery	Integration provides	Best for
Webhook	Push, at-least-once, retried	An HTTPS endpoint and a shared secret	Most integrations. Serverless backends. Quickest to integrate
WebSocket	Push, at-least-once, resumable	A consumer that reconnects and tracks an offset	Backends that cannot expose an inbound endpoint

---

Webhooks

Coming soon

Not in the current build. The design below is settled and can be planned against. It requires an HTTPS endpoint, a shared secret, and a handler that acknowledges quickly and processes asynchronously.

This sink requires the least integration work. IVK Match pushes outcomes to a configured HTTPS URL. There is no broker to run, no client library, and no polling loop, only an HTTP handler.

POST https://backend.example.com/ivk/outcomes
Content-Type: application/x-protobuf          (or application/json)
X-IVK-Delivery: 0f8c…                          unique per delivery attempt
X-IVK-Outcome-Id: 3f2b…                        stable per outcome; dedupe on this
X-IVK-Queue-Id: acme.quickplay
X-IVK-Kind: match.created
X-IVK-Timestamp: 1753600000
X-IVK-Signature: sha256=…                      HMAC over timestamp + body

Intended semantics:

Aspect	Behaviour
Success	Any 2xx. The outcome is acknowledged and will not be sent again.
Failure	Non-2xx, timeout, or connection error; retried with exponential backoff and jitter
Retry budget	Bounded; on exhaustion the delivery is parked and surfaced as an alertable metric rather than dropped
Ordering	Per queue, in order. A stuck delivery blocks that queue’s subsequent outcomes rather than reordering around it
Duplicates	Possible. Dedupe on X-IVK-Outcome-Id.
Batching	Optional; several outcomes per request to cut round trips at high volume
Encoding	Protobuf by default; JSON available for backends that cannot decode protobuf
Auth	HMAC-SHA256 signature over timestamp and body using the configured secret. Verify it, and reject stale timestamps to prevent replay.

Configuration, in the queue file:

config:
  outcomes:
    sink: webhook
    webhook:
      url: https://backend.example.com/ivk/outcomes
      secret: ${ACME_OUTCOME_SECRET}
      encoding: protobuf        # or json
      timeout_ms: 5000
      max_retries: 8

The receiving handler should ack fast and process asynchronously: persist the outcome, return 200, and do the provisioning work on the backend’s own queue. A handler that provisions a server before responding will hit the delivery timeout and cause a retry storm, with duplicate provisioning attempts as the visible symptom.

Per-queue in-order delivery means a handler that consistently fails on one poisonous outcome halts that queue’s deliveries. This is preferred over skipping a match, but it makes the parked-delivery metric something to alert on.

---

WebSocket

Coming soon

Not in the current build. Compared with webhooks, this moves reconnection and offset bookkeeping onto the client, which adds integration work.

A persistent stream for backends that want push delivery without exposing a public HTTPS endpoint: useful when the backend is behind NAT, is a dedicated-server process, or is a long-lived worker.

GET /v1/outcomes/stream?queue_id=acme.quickplay&from_offset=1234
Upgrade: websocket

Intended semantics:

• Subscribe to one queue, a namespace prefix (acme.>), or everything.
• Resumable: connect with from_offset to replay everything missed while disconnected, or omit it to start from the newest outcome.
• The client acks offsets on the same socket; acks advance the durable consumer position.
• Heartbeats and server-side idle timeouts detect half-open connections.
• Multiple concurrent consumers with independent offsets.

Compared to webhooks: lower latency, no inbound HTTPS endpoint required, but the client owns reconnection and offset bookkeeping.

Configuration, in the queue file:

config:
  outcomes:
    sink: websocket

---

Choosing a sink

Webhook is the recommended default unless the backend cannot accept an inbound connection. It matches how backends typically integrate with payment providers and platform services, it needs no client library, and there is no connection state to manage.

Choose WebSocket when an inbound HTTPS endpoint is not available: the consumer is behind NAT, it is a dedicated-server process, it is a long-lived worker, or the network policy is egress-only.

The choice is where the bookkeeping lives. Webhooks keep retries on the IVK Match side and require an endpoint. WebSockets need no endpoint and cut latency, but the client owns reconnection and offset tracking.

Either way the sink is queue configuration, so moving from one to the other is an edit rather than a migration.

---

Delivery guarantees

Identical on both sinks:

Guarantee	Holds?	Notes
At-least-once delivery	Yes	Duplicates are possible on either sink
Exactly-once delivery	No	Dedupe on Outcome.id or Match.id
Per-queue ordering	Yes	Outcomes for one queue arrive in occurrence order
Global ordering across queues	No	Independent queues are independent
Survives the consumer being down	Yes	Bounded by the retention window
Survives an IVK Match service restart	Yes	Outcomes are recorded durably before delivery

Outcome.producer_id and producer_sequence give a monotonic per-producer sequence, which is useful for detecting gaps: a consumer that sees sequence N+2 after N knows it missed one and can alert instead of carrying on.

The consumer should be idempotent. Either sink can deliver the same outcome twice: after a retry, a reconnect, or a restart between write and acknowledgement. Key session creation on Match.id and duplicates stop mattering. Suppressing them at the transport layer is more work and gives a worse result.