POST

In-app webhooks

Send a structured event when a user completes an action in your app. The platform matches event_type to campaign task mappings and may award points for tasks using INAPP_WEBHOOK verification.

Endpoint

POST${BASE_URL}/user/inapp/webhooks

Headers

Header	Required	Description
Content-Type	required	`application/json`
X-Buzz-Key-Id	required	Integration key id from admin (campaign in-app integration keys)
X-Buzz-Timestamp	required	Unix seconds (integer). Must be within ±300s of server time
X-Buzz-Signature	required	HMAC-SHA256 hex. Optional `v1=` prefix is stripped before comparison

Request body schema version 1.0

Field	Type	Rules
schema_version	string	Must be `"1.0"`
event_id	string	Your unique id (max 64 chars). Idempotency per key + environment
event_type	string	Max 64 chars. Must match an active mapping for this campaign
campaign_id	number	Positive integer. Must match the campaign bound to the integration credential
occurred_at	string	ISO 8601. Cannot be more than 7 days in the future
user.wallet	string	EVM address: `0x` + 40 hex chars. EIP-55 checksum allowed

ℹTotal JSON payload must not exceed 64 KB.

Complete example

inapp-webhook.js

const body = {
  schema_version: '1.0',
  event_id: 'evt_purchase_' + Date.now(),
  event_type: 'purchase_completed',
  campaign_id: CAMPAIGN_ID,
  occurred_at: new Date().toISOString(),
  user: { wallet: USER_WALLET },
};

const ts = Math.floor(Date.now() / 1000);
const signature = signRequest(INAPP_SECRET, ts, body);

const res = await fetch(`${BASE_URL}/user/inapp/webhooks`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Buzz-Key-Id': INAPP_KEY_ID,
    'X-Buzz-Timestamp': String(ts),
    'X-Buzz-Signature': signature,
  },
  body: JSON.stringify(body),
});

Try in playground Browse Buzzdrop tasks

Responses

200Event accepted (new), or duplicate event_id — returns prior status / awards when known.

400Schema error, payload too large, or campaign_id / credential mismatch.

401Missing or invalid headers, timestamp outside ±300s window, unknown key, or bad signature.

403In-app webhooks feature is disabled for this campaign.

429Rate limit exceeded. Check Retry-After header and implement backoff.

⚠Processing is asynchronous. After a 200, use campaign in-app event visibility to confirm awards.

← Previous

Request signing

Conversion postback