Web notifications & forwarding

Connect Bounce to any website, app, server and 3rd party service

Overview

Bounce's web notifications and secure forwarding are desgined to make it as easy as possible to integrate Bounce Link and Flex with any exisiting websites, applications and backends.

With Secure forwarding, you can add URL-based support for Bounce Link phygital authenticity and ownership verification to any custom web experience.

Web Notifications can alert your own server or any webhook-enabled service (such as Stripe, Zapier, Shopify and others) to phygital claim updates, activated experiences, secondary trades and other events.

You can use Secure Forwarding and Web Notifications to create innovative customer experiences using Bounce, while keeping all other services in sync, and with minimal integration and development work.

Web Notifications (Webhooks)

Web Notifications are webhooks, or calls to your designated URIs, in response to Bounce events. This reverse mapping from a Bounce action to your or partner APIs allows you to create dynamic triggers and respond to a range of events in real-time.

🔎 For example

Suppose you have an analytics API that is available at:

POST -> https://api.example.com/v1/track

Using Web Notifications, your API will automatically be called every time an event such as a Link Tag tap occurs, without you having to configure any SDKs, or poll any updates on your server.

Bounce Web Notifications are compliant with Standard Webhooks, promoted by Zapier and Supabase, to make it as easy as possible for your app to consume webhook notifications for bounce Link and Flex events in a trusted and predictable way. We hope this will also make it easy for 3rd party services, such as Zapier, to consume Bounce events and easily setup automated flows for emails, reporting, etc.

Event processing to web notifications flow

Currently data passed in web notification calls cannot be formatted or customized, only the URL and METHOD used to make the webhook request.

Data formatting will be supported in the future.

Notification payload & headers

As mentioned above, Bounce Web Notifications are compatible with Standard Webhooks (except for retries which are currently not supported). The data sent is considered thin according to the spec, and will only include relevant data to the event, rather than the entire data object.

The payload, signature and headers are as follows:

Notification Payload

Each notification includes:

• type - a dot notation namespace of type bounce.{product}.event

• timestamp - The timestamp of when the event occurred.

• data - event data associated with the event.

For example, for a Link phygital claim event

{
  "type": "bounce.link.claim",
  "timestamp": "2023-11-03T20:26:10.344522Z",
  "data": {
    "batch": 154,
    "id": 100
    ...
  }
}

Notification Headers

In addition to the payload, several headers are set to verify the webhook event and its associated data.

• webhook-id: the unique webhook notification identifier.

• webhook-timestamp: integer unix timestamp.

• webhook-signature: the signature of this webhook.

Notification Signature

Using the webhook-id and webhook-timestamp headers it is possible to verify the signature sent in webhook-signature, assuring the authenticity and completeness of the notification payload.

Web Notifications are signed using HMAC-SHA256 with a secret key that is available in the Developer Settings of the Bounce dashboard.

The Bounce SDK can be used to easily parse web notification payloads and verify their signatures.

Notification Events

Notification event

Complete Web Notifications event documentation is coming soon

Secure Forwarding

Secure Forwarding allows the connection of authenticated phygital claims to any website of application (via deeplinks). Forwarding is simply a redirection that occurs after a phygital tap has been verified as both authentic and valid, meaning that all of the following conditions have been met:

• The tag tapped is verified as genuine

• The unique tap is accesses within a valid time window

• The current tap is the latest one, preventing replay exploits

• Link analytics data has been collected for your project

Once authenticity and validity have been established, Bounce servers will automatically redirect the viewer to one of three routes:

Tap Event	Description
success	A URL for successful taps that pass validation For example: https://example.com/tap
failure	A URL to unsuccessful taps of identified tags For example: https://example.com/tap-error
unknown	A URL for unkown taps or unidentified tags For example: https://example.com/tap-help

You can configure your own URLs for both websites and mobile application deeplinks, making it easy to launch an app or a game directly from a phygital collectible tap.

Secure Forwarding flow from tap event to mapped URL redirection

It is possible to also configure loading pages for deeplinks that will revert to a web experience gracefully if an app is not found on a user's device. It is recommended to user universal links on iOS and App Links and Android for best mobile user experience.

Validation params and phygital data

A powerful feature of Secure Forwarding is the ability to pass unique tag data to a success URL while abstracting all the complexity of tag authenticiy validation. This means that you can easily create dynamic, tailored web and app experiences for your customers, without compromising phygital security.

For example:

• Tap to launch a mobile game and claim an exclusive in-game item

• Tap to launch a metaverse experience and claim a wearable digital twin

Tap data is passed as either encrypted or unecrypted URL parameters that can be configured via URL variable mapping.

Available variables:

• batch_id - Tag's numerical batch ID

• tag_id - Tag's numerical ID in batch

• last_tap - Last tap time as UNIX timestamp

• tap_counter - tap counter value

• tag_data - User-defined data associated with tag

• payload - All data above as base64 json

• payload_enc - All data above as encrypted base64 json

The variables can be attached to the success URL via simple variable replacement in the Developer Settings dashboard. For example:

https://www.example.com/tap?batch={batch_id}&tag={tag_id}

As mentioned, payload_enc, is encrypted to avoid passing cleartext values via URL parameters. The payload_enc is encrypted via your private-key and is meant for server-side validation.

Our upcoming SDKs can facilitate easy client-side interaction with encrypted payloads and offers simple verification and decryption methods, as well as automatically emit events when forwarding URLs and deeplinks are detected.

Securing forwarding routes

One key weakness of a forwarding-based integration is that your URLs are open for anyone to link to, including malicious sources that may try to gain access to phygital claims and exclusive content.

To avoid such exploits, it is recommended you check for the origin of the referrer on any forwarding route. This is available via document.referrer in all major browsers.

The only valid referrer for all Bounce Secure Forwarding redirections is:

https://api.letsbounce.gg

Our SDKs will validate the referrer automatically and will throw an error if an unidentified referrer attempts to pass or access Link URL params.