# Transports Pick one or more. Each transport is its own connection with its own `source_id`. ## 6.1 Webhook ``` POST https:///promo/v1/ingest/ Content-Type: application/json X-Promo-Timestamp: X-Promo-Signature: ``` ``` signature = lowercase_hex( HMAC-SHA256( secret, X-Promo-Timestamp + "." + raw_body ) ) ``` - Sign **the exact bytes you send**. Serialising the body again after signing (another key order, spaces) breaks the signature. - `X-Promo-Timestamp` must be within **±300 s** of our clock. - **Rotation.** During a rotation we accept both the current and the next secret: we give you the next one, you switch to it, we retire the old one. - **Body.** One event, or `{"events": [ … ]}` with up to **500** events; at most **1 MiB**. Other limits can be agreed in the form. - **Concurrency.** The number of requests in flight is agreed in the form; a request that finds no free slot within 0.5 s is answered `503`. | Status | Body | Meaning | Resend? | | :--- | :--- | :--- | :--- | | `200` | `{"source":"","results":[{"index":0,"event_id":"…","verdict":"accepted"}, …]}` | every event is decided; `verdict` is `accepted`, `skipped`, `rejected` or `duplicate`; `skipped` and `rejected` carry a `reason` (Appendix A). A `duplicate` may carry one too — ignore it, the event was decided earlier | no | | `503` + `Retry-After: 1` | `{"source":"","error":"undecided","results":[ …decided so far… ]}` | we could not decide an event right now; events after it were not tried | **yes — the same batch, the same `event_id`s** | | `401` | `{"error":"unauthorized","results":[]}` | missing or stale timestamp, missing signature, or a signature that matches no secret | after fixing the request | | `413` | `{"error":"body_too_large","results":[]}` / `{"error":"batch_too_large","results":[]}` | over 1 MiB, or more events than the batch limit | after splitting | | `400` | `{"error":"malformed","results":[]}` | signed, but not a JSON object, or `events` is not an array | after fixing | | `404` | `{"error":"unknown_source","results":[]}` | no active connection with this `source_id` | contact us | On `503`, any other `5xx` or a network error, resend the same batch: events already decided answer `duplicate`, the rest are decided. `{"events": []}` answers `200` with empty `results`. If a connection keeps answering `503`, contact us. Examples (standard library only), each sends one file from `examples/events/`: ```bash export PROMO_INGEST_URL=https://api.rexplay.site/promo/v1/ingest/ read -rs PROMO_SOURCE_SECRET && export PROMO_SOURCE_SECRET cd examples/webhook go run . ../events/bet.json python3 send.py ../events/settled.json ``` ``` 200 {"source":"","results":[{"index":0,"event_id":"01J8Z3K9T6-bet-778812","verdict":"accepted"}]} ``` ## 6.2 Kafka (your cluster) We connect to your cluster as a consumer. - **You give us** (form, and credentials once — §10.2): the bootstrap brokers, **every broker address the cluster advertises** with its IP, the topics, TLS — the CA, and the client certificate with its key for mutual TLS, plus the TLS server name — and SASL (`PLAIN`, `SCRAM-SHA-256` or `SCRAM-SHA-512`) with a user that may read the topics and use our consumer group. We send you the group name for your ACLs. - **TLS is required** in production. - **Message.** The record value is one event (§5.2), JSON in UTF-8. The key and the headers are not read: key the topic as your own ordering needs. - **Start.** We read from the moment we connect; tell us in the form if we should also read what the topic already retains. - **Delivery.** We commit an offset only after its event is decided. An event we could not decide is read again, so delivery is at least once; `event_id` absorbs the repeats. ## 6.3 RabbitMQ (your broker) AMQP 0-9-1 over TLS (`amqps://`, required in production). You give us the host, port, vhost, user and password, and one of: - **an exchange and routing keys** — we declare our own durable queue and bind it to your exchange. You declare the exchange; our user needs the right to declare and bind that queue. The queue holds only what arrives after we create it; or - **a queue you created for us** — our user needs the right to consume it. - **Message.** The body is one event (§5.2). Headers and properties are not read. Publish persistently so an event survives a broker restart. - **Delivery.** We acknowledge a message only after its event is decided. One we could not decide stays unacknowledged and we retry it after 1 s, doubling up to 30 s; we never requeue it. If our connection drops, the broker redelivers what we had not acknowledged, and a decided event answers `duplicate`. Several of our consumers may read one queue; order is not required.