Events API
Your server tells SentBy when an order is paid, refunded or cancelled. Every request is signed, and every event is safe to send twice.
Base URL and keys
All requests go to https://api.sentby.co.za over https. Create a secret key in SentBy under Settings, API keys. You get two values, shown once:
- the secret key (
sk_live_...orsk_test_...), sent as a bearer token; - the signing secret, used to sign each request body. It is never sent.
Test keys create test rows that never reach statements. Keep both values on your server only; the page script uses a separate publishable key that can do nothing but confirm landings.
Signing
Every request carries three headers:
| Header | Value |
|---|---|
Authorization | Bearer sk_live_... |
SentBy-Timestamp | Unix time in seconds, when you send the request |
SentBy-Signature | v1= followed by the hex HMAC-SHA256 of timestamp + "." + raw body, keyed with your signing secret |
Requests more than 5 minutes from SentBy's clock are refused with 401 and {"error":"clock_skew","server_time":...}. Correct your offset from server_time and retry once. During key rotation, both signing secrets are accepted.
import crypto from 'node:crypto';
export async function sendEvent(event) {
const body = JSON.stringify(event);
// Sign at send time, never when you queue the event.
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto
.createHmac('sha256', process.env.SENTBY_SIGNING_SECRET)
.update(timestamp + '.' + body)
.digest('hex');
const res = await fetch('https://api.sentby.co.za/v1/events', {
method: 'POST',
headers: {
'Authorization': 'Bearer ' + process.env.SENTBY_SECRET_KEY,
'Content-Type': 'application/json',
'SentBy-Timestamp': timestamp,
'SentBy-Signature': 'v1=' + signature,
'Idempotency-Key': 'paid:' + event.external_id,
},
body,
});
if (res.status >= 500 || res.status === 429) throw new Error('retry later');
return res.json();
}
BODY='{"type":"order.cancelled","external_id":"2417"}'
TS=$(date +%s)
SIG=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$SENTBY_SIGNING_SECRET" -hex | sed 's/^.* //')
curl https://api.sentby.co.za/v1/events \
-H "Authorization: Bearer $SENTBY_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "SentBy-Timestamp: $TS" \
-H "SentBy-Signature: v1=$SIG" \
-d "$BODY"
order.paid
POST /v1/events. Send it once the order is paid. For EFT, that is when you mark the payment received, not when the order is placed.
{
"type": "order.paid",
"external_id": "2417",
"ordered_at": "2026-11-26T09:10:44Z",
"paid_at": "2026-11-26T09:14:03Z",
"click_id": "sb1.01JD3H8M2Q4W7XKZP0A9BCDEF0.7Hk2pQ9x.K4M2QX7PZA",
"click_history": [],
"coupon_codes": ["BAKKIE5"],
"currency": "ZAR",
"total_cents": 168400,
"subtotal_cents": 159500,
"subtotal_tax_cents": 0,
"shipping_cents": 8900,
"discount_cents": 0,
"items": [
{ "product_id": "OSC-DT", "sku": "OSC-DT", "name": "Die Trommel", "category_ids": ["storage"],
"qty": 1, "subtotal_cents": 159500, "tax_cents": 0 }
],
"customer_ref": "h1:4f1c...",
"test": false
}
| Field | Notes |
|---|---|
external_id | Your order number. Unique per store. |
ordered_at, paid_at | ISO 8601 times. The referral window is judged on the order time. |
click_id, click_history | The _sbid and _sbh cookie values saved on the order. Omit them if there are none. |
coupon_codes | Every code used on the order. |
subtotal_cents | Line items after discounts, excluding tax and shipping. Commission is calculated on this. All amounts are whole cents in rand. |
items | Optional but recommended: product and category commission rules need them. |
customer_ref | "h1:" plus the hex HMAC-SHA256 of the buyer's email, trimmed and lowercased, keyed with your store's reference salt. Used only to detect self-purchases. Never send the email itself. |
test | With a live key, only allowed when external_id starts with sbtest- (up to 20 a day). |
You can also send up to 100 events at once as {"events":[...]}.
order.refunded and order.cancelled
{ "type": "order.refunded", "external_id": "2417", "refund_id": "r_88",
"amount_cents": 168400, "items": [ ... ] }
{ "type": "order.cancelled", "external_id": "2417" }
Include the refunded items when you have them, and SentBy reduces commission on exactly those items. Without items, commission is reduced in proportion to the amount refunded. A full refund or a cancellation reverses the sale.
Sending twice is safe
Send an Idempotency-Key header, or SentBy derives one: paid:<external_id>, refund:<refund_id>, cancel:<external_id>. The same key with the same body returns 200 and the original result. The same key with a different body returns 409.
Responses
| Status | Means |
|---|---|
202 | Accepted. Body has conversion_id, status, affiliate, commission_cents and hold_flags, or {"attributed":false}. |
200 | Duplicate of an event already received. |
400, 422 | The body is not valid. The response lists each problem. |
401 | Bad key, bad signature, or clock skew. |
403 | merchant_not_active: live events are refused until your store is verified and activated. Test events work. |
409 | Idempotency key reused with a different body. |
429 | Too many requests. Retry with backoff. |
Daily reconcile
POST /v1/reconcile once a day with up to 500 recent orders (stamped or paid in the last 60 days). SentBy answers with the ids it is missing or that differ, and you resend full events for those.
{ "orders": [ { "external_id": "2417", "status": "paid", "total_cents": 168400,
"refunded_cents": 0, "paid_at": "2026-11-26T09:14:03Z" } ] }
{ "resend": ["2419", "2422"] }
Other endpoints
| Endpoint | Use |
|---|---|
GET /v1/ping | Checks your key and signature. Returns your store and mode. |
POST /v1/products | Upserts up to 500 products for affiliates' product feeds, when your store cannot be read directly. |
POST /v1/heartbeat | Reports integration health: version, mode, platform and clock skew. Sent daily by the plugin. |
POST /v1/landing | Publishable key only. Used by the page script to confirm a landing. |