mParticle Webhooks Adapter

mParticle Webhooks Adapter Overview

mParticle is a Customer Engagement Platform that powers customer-centric interactions between consumers and brands in real time, enabling brands to create and manage communications that are tailored to individual consumers. This can include activities like sending targeted messages, personalized offers, or notifications based on customer behavior and preferences.

The mParticle and Punchh integration allows a brand to sync data across the two platforms for gifting and loyalty purposes. User data published in mParticle will be available for segmentation and can be synced with Punchh via mParticle webhooks.

Integrating mParticle with Punchh requires the creation of a specific mParticle adapter within the Webhooks Manager. For more information, see the "Webhooks Adapter" section in the mParticle Implementation article on the Support Portal.

Note: To view the Punchh product documentation on the Punchh Support Portal, you must log in to a Punchh platform production environment. If you already have access to a production environment, follow the instructions here to access the Punchh Support Portal.

Events at a Glance

Currently, Punchh supports sending data for these events to mParticle:

Exclude User Profile Data From Custom Events

By default, the "attributes" object containing user profile data sent in mParticle Event - Guest is also sent in the mParticle custom events or non-user events such as Loyalty Check-in, Redemptions, Rewards, etc. In addition to the "attributes" key, the custom events have an "events" key that contains the event data. However, you can exclude the user attributes when sending an mParticle custom event to avoid sending redundant user data and to reduce data costs. To exclude the "attributes" object, you set Disable sending default user attributes to mParticle to Yes when creating or editing your mParticle adapter in the Punchh platform.

When Disable sending default user attributes to mParticle is set to No:

  • All parameters in the user "attributes" object are sent in the mParticle Event - Guest event, regardless of whether a parameter has been updated or not.
  • The "attributes" object is available in all custom events (events that are not guest events).

When Disable sending default user attributes to mParticle is set to Yes:

  • The “attributes” object is not available for custom events.
  • The entire “attributes” object is available in the mParticle Guest Create event and will be sent as is when no mapping is present; otherwise, it will work as per the mapping.
  • Only the updated parameters are available in the “attributes” object in the mParticle Guest Update event. All changes sent in the mParticle Guest events are based on delta (updated values).
  • punchh_user_id is included in the mParticle Guest Create event only.
  • guest_type is sent only as part of the mParticle Guest Create event when the user is being converted or transitioning from eClub to Loyalty.

For more information about setting Disable sending default user attributes to mParticle in the Punchh platform, see the "Webhooks Adapter" section in the mParticle Implementation article on the Support Portal.

Note: To view the Punchh product documentation on the Punchh Support Portal, you must log in to a Punchh platform production environment. If you already have access to a production environment, follow the instructions here to access the Punchh Support Portal.

Sample Payload for Custom Events With and Without User Attributes

This is a sample payload for redemptions create/update events triggered as they happen in the Punchh system. When Disable sending default user attributes to mParticle is set to No, the sample payload will contain the default "attributes" key along with the "events" key as shown in the sample payload below.

{
  "source_request_id": null,
  "events": [
    {
      "data": {
        "product_action": {
          "action": "checkout",
          "transaction_id": "26153",
          "total_amount": 22.8600006103516,
          "tax_amount": 0,
          "shipping_amount": 0,
          "coupon_code": null,
          "products": [
            {
              "id": "3419",
              "name": "White rice",
              "price": 2,
              "quantity": 1,
              "custom_attributes": {
                "menu_family": "800",
                "menu_item_type": "M",
                "menu_major_group": "152",
                "serial_number": "1"
              }
            },
            {
              "id": "3418",
              "name": "Brown rice",
              "price": 7.86,
              "quantity": 1,
              "custom_attributes": {
                "menu_family": "800",
                "menu_item_type": "M",
                "menu_major_group": "152",
                "serial_number": "2"
              }
            }
          ]
        },
        "event_name": "eCommerce - Checkout",
        "custom_event_type": "checkout",
        "timestamp_unixtime_ms": "1621001451221",
        "event_id": "4272242131884770869",
        "custom_attributes": {
          "approved": "true",
          "bar_code": "BARCODE_GOES_HERE",
          "campaign_id": "18",
          "campaign_name": "Post Checkin - Message",
          "campaign_type": "PostCheckinCampaign",
          "channel": "OnlineOrder",
          "checkin_id": "26153",
          "checkin_type": "PosCheckin",
          "created_at": "2021-05-14T14:09:07Z",
          "earnable_amount": "22.86",
          "event_action": "create",
          "event_name": "checkins",
          "event_type": "loyalty",
          "expiring_on": "2021-05-19",
          "external_uid": "",
          "first_punchh_at_business": "false",
          "first_punchh_at_location": "false",
          "free_punchh_campaign_id": "18",
          "location_id": "110",
          "location_name": "Franhcisee Location",
          "pending_refresh": "false",
          "points_earned": "23",
          "points_spent": "0",
          "punchh_key": "PUNCHH_KEY_GOES_HERE",
          "receipt_amount": "22.86",
          "receipt_date": "2021-04-30T18:39:42Z",
          "redemption_id": "0",
          "status": "loyalty",
          "store_number": "4487",
          "transaction_no": "1424881017",
          "updated_at": "2021-05-14T14:09:07Z"
        }
      },
      "event_type": "commerce_event"
    }
  ],
  "user_attributes": {
    "Punchh_account_balance_current_membership_level_name": "Silver Level",
    "Punchh_account_balance_last_visit": "2021-05-14T14:09:07Z",
    "Punchh_account_balance_loyalty_points": "69",
    "Punchh_account_balance_net_balance": "69",
    "Punchh_account_balance_net_debits": "0",
    "Punchh_account_balance_pending_points": "0",
    "Punchh_account_balance_total_credits": "69",
    "Punchh_account_balance_total_debits": "0.0",
    "Punchh_account_balance_total_lifetime_points": "69",
    "Punchh_account_balance_total_point_credits": "69",
    "Punchh_account_balance_total_visits": "3",
    "Punchh_business_id": "6",
    "Punchh_email": "test@example.com",
    "Punchh_first_name": "FIRST_NAME_GOES_HERE",
    "Punchh_gender": "Male",
    "Punchh_guest_type": "Loyalty",
    "Punchh_last_activity_at": "2021-05-14T14:09:07Z",
    "Punchh_last_name": "LAST_NAME_GOES_HERE",
    "Punchh_marketing_email_opt_in": "True",
    "Punchh_marketing_email_subscription": "True",
    "Punchh_marketing_pn_opt_in": "True",
    "Punchh_marketing_pn_subscription": "True",
    "Punchh_secondary_email": "test1@example.com",
    "Punchh_signup_channel": "MobileEmail",
    "Punchh_sms_subscription": "False",
    "Punchh_unsubscribed": "False",
    "Punchh_user_id": "5852",
    "Punchh_user_status": "active",
    "Punchh_address": "Mi Road",
    "Punchh_city": "Jaipur",
    "Punchh_confirmation_sent_at": "2021-04-30T12:09:12Z",
    "Punchh_created_at": "2021-04-30T12:09:12Z",
    "Punchh_current_sign_in_at": "2021-04-30T12:09:12Z",
    "Punchh_current_sign_in_ip": "10.77.41.237",
    "Punchh_invite_code": "RohieEc574",
    "Punchh_joined_at": "2021-04-30T12:09:12Z",
    "Punchh_last_sign_in_at": "2021-04-30T12:09:12Z",
    "Punchh_last_sign_in_ip": "10.77.41.237",
    "Punchh_last_user_agent": "MyRewards/2.0/2 (x86_64; iOS 10.3; Scale/2.00)",
    "Punchh_referral_code": "REFERRAL_CODE_GOES_HERE",
    "Punchh_referred_by_id": "5785",
    "Punchh_state": "Rajasthan",
    "Punchh_terms_and_conditions_opt_in": "True",
    "Punchh_updated_at": "2021-04-30T12:09:12Z",
    "Punchh_zip_code": "302012",
    "Punchh_favorite_location": [
      "107"
    ],
    "Punchh_favorite_store_numbers": [
      "4456"
    ]
  },
  "deleted_user_attributes": null,
  "user_identities": {
    "email": "test@example.com"
  },
    "environment": "development",
  "ip": "",
  "integration_attributes": null,
  "source_info": {
    "channel": "partner",
    "partner": "Punchh",
    "replay_request_id": null,
    "replay_job_id": null,
    "is_historical": false
  }
}

When Disable sending default user attributes to mParticle is set to Yes, the redemptions create/update event will send only the events data in the payload.

{
  "source_request_id": null,
  "events": [
    {
      "data": {
        "product_action": {
          "action": "checkout",
          "transaction_id": "26153",
          "total_amount": 22.8600006103516,
          "tax_amount": 0,
          "shipping_amount": 0,
          "coupon_code": null,
          "products": [
            {
              "id": "3419",
              "name": "White rice",
              "price": 2,
              "quantity": 1,
              "custom_attributes": {
                "menu_family": "800",
                "menu_item_type": "M",
                "menu_major_group": "152",
                "serial_number": "1"
              }
            },
            {
              "id": "3418",
              "name": "Brown rice",
              "price": 7.86,
              "quantity": 1,
              "custom_attributes": {
                "menu_family": "800",
                "menu_item_type": "M",
                "menu_major_group": "152",
                "serial_number": "2"
              }
            }
          ]
        },
        "event_name": "eCommerce - Checkout",
        "custom_event_type": "checkout",
        "timestamp_unixtime_ms": "1621001451221",
        "event_id": "4272242131884770869",
        "custom_attributes": {
          "approved": "true",
          "bar_code": "BARCODE_GOES_HERE",
          "campaign_id": "18",
          "campaign_name": "Post Checkin - Message",
          "campaign_type": "PostCheckinCampaign",
          "channel": "OnlineOrder",
          "checkin_id": "26153",
          "checkin_type": "PosCheckin",
          "created_at": "2021-05-14T14:09:07Z",
          "earnable_amount": "22.86",
          "event_action": "create",
          "event_name": "checkins",
          "event_type": "loyalty",
          "expiring_on": "2021-05-19",
          "external_uid": "",
          "first_punchh_at_business": "false",
          "first_punchh_at_location": "false",
          "free_punchh_campaign_id": "18",
          "location_id": "110",
          "location_name": "Franhcisee Location",
          "pending_refresh": "false",
          "points_earned": "23",
          "points_spent": "0",
          "punchh_key": "PUNCHH_KEY_GOES_HERE",
          "receipt_amount": "22.86",
          "receipt_date": "2021-04-30T18:39:42Z",
          "redemption_id": "0",
          "status": "loyalty",
          "store_number": "4487",
          "transaction_no": "1424881017",
          "updated_at": "2021-05-14T14:09:07Z"
        }
      },
      "event_type": "commerce_event"
    }
  ],
  "deleted_user_attributes": null,
  "user_identities": {
    "email": "test@example.com"
  },
    "environment": "development",
  "ip": "",
  "integration_attributes": null,
  "source_info": {
    "channel": "partner",
    "partner": "Punchh",
    "replay_request_id": null,
    "replay_job_id": null,
    "is_historical": false
  }
}
Previous
Braze Event - Pending Check-in
Next
mParticle Event - Gift Check-in