KnobaseConversion event
Record a signed conversion against a returned offer snapshot.
Record a signed conversion for a previously returned offer.
Authentication
Bearer serving key required. The signature is validated separately.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| offer_snapshot_id | string (`snp_…`) | Yes | Snapshot id from the decide response. |
| decision_id | string (`dec_…`) | No | Related decision id. |
| timestamp | integer (ms) | Yes | Must be within ±10 minutes of the server clock. |
| nonce | string (8–80) | Yes | One-time value used in the signature. |
| signature | string (min 16) | Yes | Knobase-issued conversion signature. Do not invent a signing secret. |
V1 responses set billable: false and ledger_written: false. Do not invent a signing secret or publish server environment names.
Request examples
curl -sS -X POST "https://knobase.com/v1/events/conversion" \
-H "Authorization: Bearer $KNOBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"offer_snapshot_id":"snp_01EXAMPLEOFFER","decision_id":"dec_01","timestamp":1757491200000,"nonce":"nonce_example_01","signature":"aaaaaaaaaaaaaaaa"}'Response
{
"ok": true,
"inserted": true,
"event_id": "evt_02",
"offer_snapshot_id": "snp_01EXAMPLEOFFER",
"billable": false,
"ledger_written": false
}Errors
| HTTP | error | When |
|---|---|---|
| 401 | auth errors | Missing or invalid serving key |
| 401 | invalid_signature | Signature does not match |
| 400 | invalid_conversion | Body failed validation |
| 400 | expired_conversion | timestamp is outside ±10 minutes |