Receive signed server events

Verify signed JSON batches, process them idempotently, and recover failed deliveries.

Tringify sends JSON batches to the HTTPS endpoint configured for the installed release. A batch contains one store, installation, schema version, and consent purpose. It contains at most 200 events and has a 10-second request timeout.

Request headers#

Header	Purpose
`Content-Type`	Always `application/json`.
`X-Tringify-Timestamp`	Unix timestamp included in the signature.
`X-Tringify-Signature`	`t=<timestamp>,v1=<lowercase HMAC-SHA256 hex>`.
`X-Tringify-Store-ID`	Store that owns every event in the batch.
`X-Tringify-App-Install-ID`	Installation receiving the batch.

Verify the signature#

Read the raw request body before JSON parsing. Compute HMAC-SHA256 with the app signing secret over the timestamp, one literal period, and the exact raw body bytes. Compare the lowercase hexadecimal digest in constant time and reject stale timestamps before performing work.

signed-content.txt text

<X-Tringify-Timestamp>.<exact raw request body>

Batch envelope#

event-batch.json json

{
  "consent_purpose": "analytics",
  "events": [
    {
      "context": {
        "url": "https://shop.example/checkout/confirmation"
      },
      "event_id": "019f0000-0000-7000-8000-000000000001",
      "occurred_at": "2026-08-11T00:00:00Z",
      "payload": {
        "currency": "INR",
        "order_id": "66b0a1d2-4f13-4d32-a51d-93e595034e95",
        "value": "2798.00"
      },
      "schema_version": 1,
      "type": "purchase"
    }
  ],
  "schema_version": 1,
  "store_id": "f192d1f9-b01f-48c2-9300-3f3bf14716b0"
}

Acknowledge and retry#

Return any HTTP status from 200 through 299 only after the complete batch has been accepted durably. Any other response or transport failure retries with exponential delays of 1, 2, 4, 8, 16, 32, 64, 128, 256, then 512 seconds. Later retries remain at 512 seconds. After 20 unsuccessful attempts, each event enters the installation's dead-letter list.

Idempotency and ordering#

Use event_id as the idempotency key. A retry may repeat an event or batch after an ambiguous response. Do not assume batches arrive in strict event-time order, and do not make correctness depend on two event types sharing one batch.