Record a conversion / revenue event

THE CALL, PART BY PART

method

POST

host

strait.link

version

/v1

resource

/event

POST /v1/event

Auth: publishable key as publishableKey in the JSON body. Safe in apps and websites.

Request

From an app or website send publishableKey; from a server you may instead authenticate with the secret key as a Bearer token. clickId names the tap the conversion came from: every tap gets a unique id (a UUID, sent with the tap's redirect and passed to your app with the open), which the mobile SDKs remember from the attributed app open and attach for 7 days. It is kept only when it is a tap of this workspace; otherwise it is ignored and the event is still recorded. Each new event (not an eventId retry) is sent to your webhooks subscribed to app.event, with data and sentWith (publishable_key or secret_key: trust revenue sent from your server) and userId / userIdHashed (your user, when set). Webhook sends for events sent with the publishable key are capped per workspace (600 burst, then 10 a second): past that, they are still recorded but not sent. Events sent with the secret key are not capped.

Body (JSON)

publishableKey string
event required string
value number
currency string
linkId string
Optional: with a known clickId it is filled in from that tap
platform string
clickId string
The id of the tap this conversion came from (the mobile SDKs fill it in)
eventId string
Optional idempotency id, e.g. your order id: a retry with the same eventId is accepted but stored once. An event sent with your secret key replaces one sent first with the publishable key (keeping its tap and link when it has none) and is sent to your webhooks again, so a receiver de-duplicates on eventId + sentWith; nothing replaces a secret-key event.
data object,null
Optional custom key-values (at most 20, 2 KB as JSON) passed to the app.event webhook. Not stored with the event; kept 30 days with the webhook delivery. Do not send personal data your receiver does not need.
userId string
Optional: your own user id (the SDKs' setUserId), passed to the app.event webhook as userId so you can join events to your users. Not stored with the event; kept 30 days with the webhook delivery. An email (any @, @ or ﹫) or phone number (8-15 digits with spaces, dashes, dots, brackets or slashes, an optional + / 00 / tel:; Indian, Arabic and full-width digits too) is replaced by its SHA-256 hex (of the lower-cased email; of + and the digits when written with + or 00, else of the digits, e.g. sha256("+919876543210")) and sent with userIdHashed: true; the SDKs do this on the device. Trimmed; empty, longer than 128 characters or with control characters = dropped (the event is still recorded). Sent with the publishable key, userId is a claim anyone with your app key can make: trust it only on sentWith: secret_key events or check it against your own records.
userIdHashed boolean
True when userId is already the SHA-256 of an email or phone as 64 lower-case hex characters (the SDKs set it); anything else is treated as a raw id.

Response

  • 202 Accepted. clickId echoes the tap id that was stored, or null when none was given or it was not a tap of this workspace.
  • 401 Missing or invalid key
Request · curl
curl -X POST https://strait.link/v1/event \
  -H "Content-Type: application/json" \
  -d '{
    "publishableKey": "st_pub_live_…",
    "event": "purchase",
    "value": 499,
    "currency": "INR",
    "clickId": "9a1c7e52-4b3d-4f8e-a6d1-0c2b5e7f9a34",
    "eventId": "ord_1001",
    "data": {
      "plan": "gold"
    },
    "linkId": "<link id from POST /v1/links>"
  }'

The response, printed

Response 202
{
  "ok": true,
  "clickId": "9a1c7e52-4b3d-4f8e-a6d1-0c2b5e7f9a34",
  "linkId": "lnk_5f0c2a8e-3b1d-4f6a-9c7e-2d8b1a0e4f63"
}