Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Postback URLs & deep links · Boson Protocol
Skip to content

Postback URLs & deep links

Widget interactions are off-server by default — the buyer's browser talks to the chain. To capture events on your backend (record the order in your CRM, fire fulfillment), use a postback URL.

Configure

<button
  id="boson-commit"
  data-config-id="..."
  data-postback-url="https://yourserver.example.com/boson/postback">
  Buy now
</button>

Payload

The widget POSTs JSON to your endpoint after each lifecycle event:

{
  "event": "committed",
  "exchangeId": "456",
  "buyer": "0x...",
  "offerId": "123",
  "txHash": "0x...",
  "configId": "production-137-0",
  "timestamp": 1742345678
}

Events: committed, redeemed, disputed, cancelled, revoked.

Authentication

The widget signs the payload with HMAC using a secret you supply at widget config:

data-postback-secret="<your secret>"

Verify on your server using the matching secret.

Deep links

To open the widget from a URL (e.g. a deep link in an email):

https://widgets.bosonprotocol.io/#/commit?configId=production-137-0&productUuid=...&account=0x...

The widget mounts in fullscreen mode. Useful for share / claim links.

Common gotchas

  • Postbacks are not retried by default. If your endpoint is down, the event is lost. Pair with a webhook server that listens to on-chain events as a backstop.
  • HMAC verification is mandatory in production. Without it, anyone can POST to your endpoint with fake events.

Next