SendEvent1

• bhidbubbleflakerequired

  Unique Bubblehouse event identifier that can be used for deduplication.

• timetimerequired

  Timestamp when the event occurred.

• namestringrequired

  Human-readable event name.

  Common event names include:

  • "Points Updated" - Customer's point balance changed
  • "Points Earned" - Points were added to customer's balance
  • "Points Redeemed" - Points were spent on a reward
  • "Points Expired" - Points expired based on expiration rules
  • "Tier Reached" - Customer achieved a new tier
  • "Asset Unlocked" - Achievement was unlocked
  • "Vendible Redeemed" - Customer redeemed a vendible reward
  • "Referral Approved (Sender)", "Referral Approved (Receiver)" - Referral was successfully completed
  • "Birthday" - Customer's birthday event
  • "Anniversary" - Customer's membership anniversary
• customerCustomerIdentityWithName1required

  Customer identification and name information.

  Contains the following fields:

  • bhid - Bubblehouse customer ID
  • shopid - Your ecommerce platform's customer ID
  • email - Customer email address
  • first_name - Customer's first name
  • last_name - Customer's last name
  • full_name - Customer's full name
• customer_propsmapoptional

  Customer loyalty properties and attributes.

  Contains comprehensive customer data including:

  • BH_Points_Balance - Current point balance
  • BH_Points_NextExpiration_Amount and BH_Points_NextExpiration_Date - Points expiring soon
  • BH_Tier - Current tier name
  • BH_MagicLink - Magic login link if enabled
  • and many others
  • plus custom attributes configured for your tenant
• segment_propsmapoptional

  Event-specific segmentation properties.

  Contains data specific to the event type, which can be used for indexing and segmentation. For example:

  • For Points Earned event: BH_Source
  • For Tier Reached event: BH_Tier (new tier name)
  • For Achievement Unlocked event: BH_Achievement (achievement name)
  • For Referred (Receiver) event: BH_Channel, BH_HasCoupon
• extra_propsmapoptional

  Additional event-specific properties.

  Contains data specific to the event type that should not be indexed (e.g. names, coupon codes, URLs), for example:

  • For Points Earned event: BH_Points
  • For Tier Reached event: BH_Reward_Coupon
  • For Referred (Receiver) event: BH_Sender_FirstName, BH_Sender_Email, BH_Link

  Many services don't distinguish between segmented and non-segmented event properties; if you don't care about the difference, treat this as an extension of segment_props.

• new_userbooleanoptional

  True if this is expected to be a new customer (i.e. is a referral event send to the person being referred).

• referred_userbooleanoptional

  True if this is one of referral events sent to the customer being referred.

  Unlike new_user, this one is also true for referral approval events, by which time the customer should no longer be new.

• customer_onlybooleanoptional

  True if this event only updates customer properties without representing an actual event.

  When true, treat this as a customer profile update rather than an activity event. Useful for syncing customer data without triggering event-based automations. You can ignore the event name.

• outcomeSendEventOutcomerequired

  Result of processing the event, controlling retry behavior.

  Must be one of the following values:

  • "sent" - Event successfully processed and sent to destination
  • "skipped" - Event intentionally not processed (e.g., filtered by rules)
  • "invalid_data" - Event contains invalid data that cannot be processed
  • "unsubscribed" - Customer has opted out of receiving events
  • "failure" - Temporary failure, event should be retried

  The outcome determines whether the event is removed from the queue (sent, skipped, invalid_data, unsubscribed) or kept for retry (failure).

Usage Examples

{
  "bhid": "24a5be6c83010001",
  "time": "2024-12-26T18:05:42.915Z",
  "name": "Points Updated",
  "customer": {
    "bhid": "24760933ea010001",
    "shopid": "12345",
    "email": "customer@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "customer_props": {
    "BH_Points_Balance": 500,
    "BH_Tier": "Gold"
  },
  "segment_props": {
    "BH_Source": "order"
  },
  "extra_props": {
    "BH_Points": 50,
    "order_id": "ORDER-789"
  }
}

// Example webhook handler
app.post('/webhook/SendEvent1', async (req, res) => {
  const event = req.body;

  // Validate event data
  if (!event.customer.email && !event.customer.shopid) {
    // Missing required customer identifier
    return res.json({ outcome: 'invalid_data' });
  }

  // Check if customer is subscribed
  const isSubscribed = await checkSubscriptionStatus(event.customer.email);
  if (!isSubscribed) {
    return res.json({ outcome: 'unsubscribed' });
  }

  // Process based on event type
  switch (event.name) {
    case 'Points Updated':
      await updateCustomerPoints(event.customer, event.segment_props, event.extra_props);
      res.json({ outcome: 'sent' });
      break;
    case 'Tier Reached':
      await triggerTierCampaign(event.customer, event.segment_props, event.extra_props);
      res.json({ outcome: 'sent' });
      break;
    default:
      return res.json({ outcome: 'skipped' });
  }
});

{
  "outcome": "sent"
}