Checkout Events and Webhooks

Browser events

The hosted frame sends:

• loaded when the session is ready;
• payment-success after checkout confirmation;
• payment-error when the payment cannot continue;
• payment-canceled when the customer closes checkout.

Validate the Belong origin and the source window:

import { BELONG_CHECKOUT_ORIGIN, isPaymentEvent, PaymentEvent } from '@belongnet/sdk'

function onMessage(event: MessageEvent) {
  if (event.source !== frame.contentWindow) return
  if (!isPaymentEvent(event, BELONG_CHECKOUT_ORIGIN)) return

  switch (event.data.type) {
    case PaymentEvent.Loaded:
      hideLoadingState()
      break
    case PaymentEvent.PaymentSuccess:
      showWaitingForServerConfirmation()
      break
    case PaymentEvent.PaymentError:
      showError(event.data.payload.error)
      break
    case PaymentEvent.PaymentCanceled:
      closeCheckout()
      break
  }
}

These events control storefront UI only.

Signed server webhook

The order source of truth is the checkout.completed webhook. Belong sends the exact JSON body with:

x-belong-event-id: checkout-completed-{checkoutId}
x-belong-signature: v1={hex_hmac_sha256}

Compute HMAC-SHA256 over the raw request body using the webhookSecret returned when the session was first created. Compare signatures in constant time, reject invalid requests, and make processing idempotent by x-belong-event-id.

The payload includes the external order ID, transaction hash, amount, payment token, chain, collection address, minted token IDs, and owner wallet.

Return any 2xx response only after the event is durably recorded. An authorized backend can use the webhook retry endpoint if delivery needs to be repeated.