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 effort 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 Architecture
Transactions
All interactions with a blockchain happen through transactions. These aren't necessarily financial transactions or involve 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 transactions 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 offer our own hash that represents a promise on the confirmation of a given action, which you can find as actionPromise in the response. This is returned instantly with each request made and can be queried against the actions endpoint to retrieve the status of a request as well as additional blockchain information.
Recieving Transaction Confirmations
There are two mechanisms available for receiving the blockchain confirmation and txHash of the transaction:
Polling
By using the actionPromise returned for every action, polling for blockchain confirmation status becomes possible by using Actions with the received actionPromise parameter. Once confirmed will return the blockchain txHash that can then be viewed on a blockchain explorer as well as the eventAddress that represents the smart contract address for that event, and the tokenId of the NFT the action related to.
Although it is possible to poll the Actions endpoint for confirmation statuses we recommend setting up a webhook for real-time and time-sensitive confirmations. Where webhooks are not possible we recommend using a back-off strategy to avoid excess requests.
Webhooks / Callbacks
All submitted actions will receive a actionPromise in the response body, but events that have been created with a callbackUrl will also receive a callback to the URL provided with this promise ID. For event-driven systems this offers you the ability to offer your users notification of ticket confirmation in real-time as you will only recieve the callback when there is updated data ready to be fetched.
Since the callback includes the promise ID, you are then able to use this to request the updated data from the Actions endpoint.
See the Callbacks section 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
eventIdis 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 using your application routing. - 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 which will be respected when the callback is sent.
Examples
https://api.myticketcompany.com/events/<eventId>/nft_webhookhttps://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.