Campaign event

A campaign's players were granted their rounds, or the campaign expired or was cancelled. event_id is the deduplication key: an unacknowledged event, a 5xx included, is resent with the same event_id. A win of a free round is a walletWin that carries the campaign.

POST/campaign-event

Request

The aggregator sends this request to the client's wallet base URL, signed with the client's credential like a client request, and the client's wallet answers it. The example is signed with the test API key test-key-test-key and the test secret docs-example-signing, at the timestamp 1767225600 with the nonce docs-example-nonce-0001; see Authentication and signing.

Headers

Name
X-Api-Key
Type
string, required
Description
The credential id. Sent together with X-Timestamp, X-Nonce and X-Signature.
Name
X-Signature
Type
string, required
Description
Base64 HMAC-SHA256 of the method, the path with its query, X-Timestamp, X-Nonce and the lowercase hex SHA-256 of the raw body, joined by newlines. Compared in constant time; 30 seconds of tolerance; each nonce is used once.
Name
X-Timestamp
Type
string, required
Description
Unix seconds; within 30 seconds of the receiver's clock. Matches ^[0-9]{1,12}$.
Name
X-Nonce
Type
string, required
Description
Single use per credential, kept until the timestamp plus 30 seconds. At least 16 characters. At most 128 characters.

Body

Name
event_id
Type
string (uuid), required
Description
A UUID v7.
Name
type
Type
string, required
Description
One of granted, expired, cancelled.
Name
campaign_id
Type
string (uuid), required
Description
A UUID v7.
Name
code
Type
string, required
Description
The client's campaign code, unique per client. Matches ^[A-Za-z0-9_.:-]{1,64}$.
Name
occurred_at
Type
string (date-time), required
Description
Name
players
Type
string[]
Description
The players granted, on a granted event only. At most 500 items. Each item: at least 1 character. At most 44 characters.

Request

POST

/campaign-event

curl -X POST "https://wallet.example.com/campaign-event" \
  -H "X-Api-Key: test-key-test-key" \
  -H "X-Timestamp: 1767225600" \
  -H "X-Nonce: docs-example-nonce-0001" \
  -H "X-Signature: gduhBvOKZoYsqYj226UbwGb61V37wAQ5oeFpPDRoc0M=" \
  -H "Content-Type: application/json" \
  -d '{
  "event_id": "0199c5a0-0000-7000-8000-000000000009",
  "type": "granted",
  "campaign_id": "0199c5a0-0000-7000-8000-000000000009",
  "code": "text",
  "occurred_at": "2026-10-13T12:00:00Z",
  "players": [
    "text"
  ]
}'

200

Response

The answer is 200 with no body.

Errors

Each error carries one of these codes in the error object of Errors.

Name
MALFORMED_REQUEST
Type
400
Description
MALFORMED_REQUEST: the request fails the client's validation. A final refusal.
Name
UNAUTHORIZED
Type
401
Description
UNAUTHORIZED: a missing or wrong key, signature, timestamp or nonce. A final refusal.
Name
INTERNAL_ERROR
Type
5XX
Description
A 5xx, a timeout, or a network error is an unknown outcome. Any status or body this document does not list as a refusal is also an unknown outcome. This includes a 4xx whose body carries none of the canonical codes. A body, when there is one, has the wallet error shape with INTERNAL_ERROR, the only code the error table gives a 5xx. The aggregator treats any 5xx as an unknown outcome whatever its body.