The underlying blockchain environment is public and competitive, and the available resource space for confirming transactions can be limited even on the most advanced chains. During times when the network is under high load returning a transaction confirmation within the HTTP response timeout is not feasible, so for this reason should be treated as an asynchronous operation in all cases and the API is designed as such.

Blockchain Primer

Consistently writing transactions at scale onto any blockchain is not an easy task, and avoiding this work may be one of the reasons you're considering GET Protocol. The Ticket Engine abstracts away a lot of the mayhem, but it is still worth having a surface level understanding of the primitives beneath and how they can affect the system architecture above.

High-Level Ticket-Engine ArchitectureHigh-Level Ticket-Engine Architecture

High-Level Ticket-Engine Architecture

Transactions

All interactions with a blockchain happen through transactions. These aren't necessarily financial transactions or mean transacting money to another party, rather the terminology here is similar to a database transaction. All writes to a blockchain network happens via these transactions. When a transaction is confirmed the blockchain generates and returns a transactionHash or txHash unique to that transaction.

The Polygon and Ethereum documentation covers these in more depth:

Blockchains are notoriously competitive environments and parties all over the world are attempting to have their transactions confirmed with limited throughput available for everyone. This is handled by the gas fee market which allows people to bid higher amounts to have their transactions included more quickly.

GET Protocol handles this by using a number of pricing algorithms and intelligent batching to ensure cost effectiveness as well as quick confirmation. Out NFT smart contracts are highly gas optimised to result in the best possible throughput needed for high volume ticket sales.

Guarantees

Since the transaction confirmation time cannot be guaranteed it would not be feasible to return a blockchain-generated txHash in the response body of each Ticket Engine request. Instead we have abstracted that away and offer our own hash that represents a promise on the confirmation of a transaction, which you can find as txPromise in the response. This is returned instantly with each request made.

Recieving Transaction Confirmations

There are two mechanisms available for receiving the blockchain confirmation and txHash of the transaction:

Polling

By using the txPromise returned on every request, polling for blockchain confirmation status becomes possible by using List Transactions with the txPromise parameter and once confirmed will return the blockchain txHash that can then be viewed on a blockchain explorer.

When polling the List Transactions endpoint for confirmation we recommend using a back-off strategy to not overload this endpoint and using a webhook for real-time and time-sensitive confirmations.

Webhooks / Callbacks

All transactions will receive a txPromise in the response body, but events that have been created with a callbackUrl will also receive a callback to the URL provided. For event-driven systems this offers you the ability to offer your users notification of ticket confirmation in real-time.

See the Event Callback and Ticket Callback sections for more information on the structure of the data passed to the callbackUrl

Designing your Webhooks

A unique callbackUrl can be defined per-event and all transactions related to that event will be returned to that URL. Confirmations for the tickets associated to that event will also go to the event callbackUrl. The webhook must be secured using HTTPS for the request to be made.

Since the webhook URL can be unique to each event created on the Ticket Engine and is not stored publicly on-chain you may wish to consider:

  • Adding the eventId to the URL. The eventId is passed as JSON so this isn't required, but you would more easily be able to restrict access and deprecate the endpoint when your event is finished.
  • Passing an access key as part of the query string. The callback will be sent to the full URL so this would allow you to add a separate token to the URL.

Examples

  • https://api.myticketcompany.com/events/<eventId>/nft_webhook
  • https://www.acme.events/hooks/<eventId>?token=<token>

Retries & Successes

The callback will use an exponential back-off for timing and will make a total of 5 attempts to receive a successful 200 OK response from the webhook API.