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_... or sk_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:

HeaderValue
AuthorizationBearer sk_live_...
SentBy-TimestampUnix time in seconds, when you send the request
SentBy-Signaturev1= 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.

Nodejs
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();
}
Shellbash
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"

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.

Request bodyjson
{
  "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
}
FieldNotes
external_idYour order number. Unique per store.
ordered_at, paid_atISO 8601 times. The referral window is judged on the order time.
click_id, click_historyThe _sbid and _sbh cookie values saved on the order. Omit them if there are none.
coupon_codesEvery code used on the order.
subtotal_centsLine items after discounts, excluding tax and shipping. Commission is calculated on this. All amounts are whole cents in rand.
itemsOptional 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.
testWith 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

Request bodiesjson
{ "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

StatusMeans
202Accepted. Body has conversion_id, status, affiliate, commission_cents and hold_flags, or {"attributed":false}.
200Duplicate of an event already received.
400, 422The body is not valid. The response lists each problem.
401Bad key, bad signature, or clock skew.
403merchant_not_active: live events are refused until your store is verified and activated. Test events work.
409Idempotency key reused with a different body.
429Too 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.

Request and responsejson
{ "orders": [ { "external_id": "2417", "status": "paid", "total_cents": 168400,
                "refunded_cents": 0, "paid_at": "2026-11-26T09:14:03Z" } ] }

{ "resend": ["2419", "2422"] }

Other endpoints

EndpointUse
GET /v1/pingChecks your key and signature. Returns your store and mode.
POST /v1/productsUpserts up to 500 products for affiliates' product feeds, when your store cannot be read directly.
POST /v1/heartbeatReports integration health: version, mode, platform and clock skew. Sent daily by the plugin.
POST /v1/landingPublishable key only. Used by the page script to confirm a landing.