Server API (/v1/s)

Send events from your own backend with the site secret: payload, hashing, responses and limits.

Endpoint

POST https://cloudbase.click/v1/s
Authorization: Bearer ss_your_server_secret
Content-Type: application/json

The server secret is on your site page (shown once; "Issue new server secret" makes a new one). Keep it on your server — never in browser code.

Payload

{
  "events": [
    {
      "event_name": "Purchase",
      "event_id": "purchase_1042",
      "event_time": 1761638400,
      "url": "https://yourshop.com/checkout/thank-you",
      "user_data": {
        "em": "[email protected]",
        "ph": "8801712345678",
        "fn": "rahim",
        "external_id": "cust_42",
        "ip": "103.120.10.20",
        "ua": "Mozilla/5.0 (…)",
        "fbp": "fb.1.1761630000.123456789",
        "fbc": "fb.1.1761630000.IwAR…"
      },
      "custom_data": { "value": 2500, "currency": "BDT", "content_ids": ["sku-1"], "num_items": 2 }
    }
  ]
}

Up to 100 events per request, 64 KB body. A single event object (without events) also works.
event_id: use the same ID as the browser event to deduplicate. Missing → we create one.
event_time: Unix seconds, at most 7 days old; missing → now.
Customer fields em, ph, fn, ln, ct, st, zp, country, ge, db, external_id may be plain (we normalise and SHA-256 hash them on arrival) or already hashed (64-char hex is kept).
ip and ua must be the shopper's, not your server's — Meta needs them to match.

Responses

202 {"accepted":1,"event_ids":["purchase_1042"]}
202 {"accepted":1,"event_ids":[…],"forwarded":false,"reason":"quota_exceeded"}
401 {"error":"unauthorized"}          wrong or missing secret
413 too many events / body too large
422 no valid events (event_name missing)

202 means queued; delivery to Meta happens within seconds and is retried on errors. Check the result in the Event log. Retry on network errors and 5xx/429 with back-off.

Example (curl)

curl -X POST https://cloudbase.click/v1/s \
  -H "Authorization: Bearer ss_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{"event_name":"Lead","event_id":"lead_77","user_data":{"em":"[email protected]","ip":"103.120.10.20","ua":"Mozilla/5.0"}}'

Stuck? Ask for setup help — we answer in বাংলা or English.