Developer Platform

Webhooks

Subscribe to real-time platform events

Webhooks push events to your server the moment they happen — installs, purchases, reviews, release scans — so you don't have to poll.

Subscribe

curl -X POST https://api.theaimart.co/api/v1/webhooks \
  -H "Authorization: Bearer $THEAIMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/theaimart",
    "events": ["listing.installed", "purchase.completed", "review.created"]
  }'

The response includes a signing secret (whsec_…) — store it to verify deliveries.

Event catalog

EventFires when
listing.installedA user installs your app/web app/agent
purchase.completedA one‑time purchase settles
subscription.created / subscription.canceledSubscription lifecycle
app.build.scannedA build finishes malware scanning
release.created / release.rolled_backRelease lifecycle
review.createdA buyer leaves a review
payout.paidA payout settles to your account

Payload shape

{
  "id": "evt_2Nk...",
  "type": "purchase.completed",
  "created": "2026-07-01T12:34:56Z",
  "data": {
    "listing_id": "app_123",
    "buyer_id": "usr_9f...",
    "amount": 499,
    "currency": "INR"
  }
}

Verify every delivery

Each request carries X-theaimart-Signature: t=<ts>,v1=<hmac>. Compute HMAC‑SHA256 over "{t}.{raw_body}" with your signing secret and compare:

import crypto from "crypto";

export function verify(rawBody, header, secret) {
  const [t, v1] = header.split(",").map(p => p.split("=")[1]);
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  const ok = crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
  // Reject if signatures differ or the timestamp is older than ~5 minutes.
  return ok && Math.abs(Date.now() / 1000 - Number(t)) < 300;
}

Verify the signature before trusting a payload, and reject stale timestamps to block replay attacks. Never act on an unverified webhook.

Reliability

  • •Respond 2xx within 5s; do heavy work asynchronously.
  • •Failed deliveries retry with exponential backoff for up to 24h.
  • •Deliveries can repeat — make your handler idempotent using the event id.

Next