Structure

The webhooks JSON payload has always the same fields structure.

  • id - unique id for the event in the Betterez Webhooks Platform. If there are more than one subscriber for the same webhook they will receive equal ids).
  • attemptId - unique id for the posting webhook action. It will be totally unique, no matter if there are more than one subscriber for the same webhook.
  • livemode - set in false for test purposes, always true.
  • created - the utc time when the webhook was emitted.
  • event - the event name, i.e: transaction.completed.
  • data - the data for the event ocurred.
{
  "id": "string",
  "attemptId": "string",
  "livemode": "boolean",
  "created": "int",
  "event": "string",
  "data": {
    ...
  }
}

Shift location (shiftLocation)

Many webhook payloads include a shift location object. It describes the station/location where the agent had an open shift when the action was performed. The same structure is used in:

  • Shift events (shift.created, shift.closed, shift.updated, shifts.deposit.created, etc.): in data.location (the shift’s location).
  • Transaction events (transaction.completed, transaction.updated, etc.): in data.transaction.shiftLocation and in each item in data.tickets, data.parcels, etc., as shiftLocation on the item.
  • Ticket events (ticket.created, ticket.updated, etc.): in data.shiftLocation.
  • Sold item events (solditem.created, solditem.updated): in data.shiftLocation.
  • Refund events (refund.created): in data.shiftLocation.
  • Redeemable item events (redeemableitem.created, redeemableitem.updated): in data.shiftLocation (empty object when purchased via websales).
  • Parcel events (parcel.created, parcel.updated, parcel.scan.created): in data.shiftLocation.
  • Gift certificate events (giftcertificate.created, giftcertificate.updated): in data.shiftLocation.
  • Parcel/manifest events: in data.shiftLocation on parcels and related items where the sale was made from a shift.

Shift location object (all fields may be present; string fields may be empty):

Property Type Description
name string Name of the station assigned as the location for the shift.
stationId string Id of the station (e.g. "635840d967f9a073479a42b6").
country string Two-letter ISO code for the country (e.g. "CA").
province string Province/state for the station (e.g. "Ontario").
shortcode string Shortcode of the location.
latitude string Latitude of the location.
longitude string Longitude of the location.
costCenter string Cost center used for deposit information for the location.
operatingCompanyId string Id of the operating company associated with the location.
operatingCompanyName string Name of the operating company.
locationPurchaseLimits object Purchase limits for this shift location (e.g. per-currency limits).
primaryCurrencyCode string ISO code of the primary currency for the location (multi-currency accounts).
acceptedCurrencies array of string Currencies accepted at the location.
externalId string External identifier for the station/location.
timeZone string IANA time zone of the location (e.g. "America/Toronto"). Set from the station when the shift is opened, or from account preferences when the station has no time zone.
regionId string Id of the region the station is assigned to (24-character ObjectId, e.g. "6516b9ac9e6f5a2c1ad7a9d1"). Empty string when the station has no region assigned.
regionName string Name of the region the station is assigned to (denormalized from the region at station save time, e.g. "Pacific Coast"). Empty string when the station has no region assigned.

Both regionId and regionName are derived from the station that the shift is opened against. When a transaction is created from an open shift, the same regionId / regionName are copied into the shiftLocation of the transaction (and into each item's shiftLocation), so any downstream webhook that carries a shiftLocation (transactions, tickets, parcels, sold items, refunds, redeemable items, gift certificates, vouchers, deposits, etc.) will surface the same region values that were on the shift's location.

For paid flows, many Sales webhooks include paidAt as a BzDate object:

{
  "paidAt": {
    "value": "2026-01-01T00:00:00.000Z",
    "offset": 0
  }
}
  • value: UTC ISO datetime for when the object first reached paid state.
  • offset: timezone offset (typically 0 in webhook payloads).

paidAt is set once on first paid transition and preserved on later retries/updates. You can find it in objects emitted by events like transaction.completed / transaction.updated (transaction and summary items), ticket.*, solditem.*, redeemableitem.*, parcel.*, insurance.*, giftcertificate.*, and loan.* when those items are paid.