Webhooks & events

Marketplace operators need to react to on-chain state changes — a new offer, a commit on a listed offer, a dispute, a redemption. Three eventing surfaces are available; see Concepts → Eventing & indexing for the canonical reference.

A simple webhook listener (RPC)

import { ethers } from "ethers"
import offerAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonOfferHandler.json"
import exchangeAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonExchangeHandler.json"
import disputeAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonDisputeHandler.json"
 
const diamond = new ethers.Contract(DIAMOND_ADDRESS, [...offerAbi, ...exchangeAbi, ...disputeAbi], provider)
 
const handlers: Record<string, (args: any) => Promise<void>> = {
  OfferCreated: async (args) => postToCRM("offer_created", args),
  BuyerCommitted: async (args) => postToCRM("buyer_committed", args),
  VoucherRedeemed: async (args) => postToCRM("voucher_redeemed", args),
  DisputeRaised: async (args) => postToCRM("dispute_raised", args),
}
 
for (const [evt, fn] of Object.entries(handlers)) {
  diamond.on(evt, (...args) => fn(args))
}

Reorg-safe pattern

1. Receive event
2. dedupe = `${txHash}:${logIndex}`
3. if (alreadyProcessed(dedupe)) return
4. wait N confirmations  // 2-3 L2, 12+ L1
5. process
6. mark processed

See Recipes → Webhook server for a full implementation.

Subgraph polling

For lower-volume use cases, poll the subgraph every 30s:

setInterval(async () => {
  const newOffers = await sdk.getOffers({
    where: { createdAt_gt: lastSeenCreatedAt.toString() },
    orderBy: "createdAt",
    orderDirection: "asc",
  })
  for (const o of newOffers) await process(o)
  lastSeenCreatedAt = newOffers.at(-1)?.createdAt ?? lastSeenCreatedAt
}, 30_000)

Critical events for marketplace operators

Event	Reason to listen
`OfferCreated`	Index for search; notify followers of seller
`OfferVoided`	Remove from search; refund pending displays
`BuyerCommitted`	Update inventory; notify seller; award protocol-agent fee
`VoucherRedeemed`	Trigger fulfillment; close pre-order list
`DisputeRaised`	Pause inventory; surface support flow
`ExchangeCompleted`	Update reputation / score; close order

A simple webhook listener (RPC)

Reorg-safe pattern

Subgraph polling

Critical events for marketplace operators

Next