Notes

UPDATE- August 7th, 2020

We have added capabilities to SkyBox’s webhooks that result in the following:

• Inclusion of a generatedBySameAccount field.

  • This field will show a ‘true’ value if the event that triggered the push notification you are receiving was authored by the same application through which you registered for the webhook you’re receiving a notification through. This is determined based on the Application Token used to register for the Webhooks subscription.

  • The field will show a ‘false’ value when the author of the change is not the same application which registered for the webhook in question.

  • For example: Application A makes an API call to SkyBox to create a new Invoice, Invoice ID 111. Application A has also subscribed to an Invoice Creation webhooks subscription. When the push notification for Invoice ID 111 is sent, the generatedBySameAccount field will show a ‘true’. This allows Application A to ignore any changes it has made itself, as it presumably would not need a push notification to inform it of a change it has itself executed.

  • Note- If you still wish to receive and act upon push notifications for changes your application has made, you can simply ignore the value in this field.

• Inclusion of Current and Previous values for ‘Update’ push notifications.

  • ‘Updates’ of existing entities in SkyBox will now contain ‘Current’ and ‘Previous' values for values that have been changed in the ‘Update’ that triggered the push notification.

  • The ‘Current’ section will simply be named something like ‘invoice’ (i.e. the name of the entity for which the update is being sent.

  • Note- This only includes some of the fields associated with each entity. The fields included in the ‘current’ and ‘previous’ structure are the same as those included in the ‘CREATED’ and ‘DELETED' notifications, as outlined below.

  • Example:

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { "id":1663168, "accountId":1, "topic":"PURCHASE", "action":"UPDATED", "generatedBySameAccount":false, "purchase":{ "tags":"sports", "outstandingBalance":40.0, "totalAmount":40.0 }, "previous":{ "tags":null, "outstandingBalance":30.0, "totalAmount":30.0 } }

• Inclusion of relevant fields on ‘CREATED’ and ‘DELETED’ push notifications.

  • Select relevant values will now be included in the body of push notifications for the creation (and deletion) of the various entities in SkyBox. This allows you to potentially take actions based on these events without having to make a follow-up API call to SkyBox to retrieve full details on the entity in question.

  • The fields included with each entity are as follows:

    • Inventory- inHandDate, eventId, quantity, section, row, lowSeat, highSeat, cost, ticketIds, stockType, splitType, listPrice, publicNotes, attributes, tags, exchangePosId, broadcast, zoneSeating, hideSeatNumbers, shownQuantity, filesUploaded, barCodesEntered

    • Purchase- vendorId, paymentMethod, tags, paymentStatus, externalRef, currencyCode, outstandingBalance, total amount

    • Invoice- customerId, paymentMethod, internalNotes, publicNotes, tags, paymentStatus, fulfillmentStatus, externalRef, currencyCode, outstandingBalance, barcodesEntered, filesUploaded, total amount

    • Line- quantity, description, amount, itemIds, cancelled, inventoryIds

    • Hold- inventoryId, expiryDate, customerId, externalRef, quantity, section, row, seats, cost, listPrice, eventId

  • Note- This is not necessarily meant to completely eliminate ‘follow-up’ API calls to retrieve full details. The fields chosen represent the best estimation of the fields most necessary for actions taken by monitoring applications.

  • Example:

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { "id":1663177, "accountId":1, "topic":"PURCHASE", "action":"CREATED", "generatedBySameAccount":false, "purchase":{ "vendorId":135, "paymentMethod":"CREDITCARD", "tags":"", "externalRef":null, "paymentStatus":"UNPAID", "currencyCode":"USD", "outstandingBalance":70.0, "totalAmount":70.0 } }

Headers

All the endpoints consume and produce application/json. All three below headers are required for authentication:

X-Application-Token

• Used to identify the app making the request

X-Api-Token

• Used to identify the account authorization

X-Account

• Used to identify the SkyBox account

Endpoints

The following endpoints are available to configure Webhook subscriptions to receive Webhook notifications:

GET /webhooks

Returns all the Webhook subscriptions configured by the application on the account specified in the authentication headers.

POST /webhooks

Used to create a Webhook subscription. The request body must have the following fields:

topic	one of the accepted topics (INVENTORY, PURCHASE, INVOICE, LINE, HOLD)
url	the URL where the webhook notifications must be sent. E.g. “https:mydomain.com/skybox/webhooks”. The webhook notification will be sent to this URL using a POST http request with the notification event data in the body
headers	the headers that the http requests of the Webhook notifications must have for security, identification or any reason that a header is needed. E.g. “User: SkyTest,Password: password,Id: SkyboxWebhooks“
secret	key used to create a HmacSHA1 Message Authentication Code (MAC) with the payload of the message. This hex string is sent in a header called Webhooks-Signature

PUT

Used to modify a Webhook subscription. The request body must have the same fields used in creation. The id of the Webhook to update must be included as path parameter.

DELETE

Used to delete a Webhook subscription. The id of the webhook to delete must be included as path parameter.

GET

Used to retrieve a Webhook subscription in particular. The desired webhook ID must be included as path parameter.

Webhook Notification

Topics:

SkyBox will send a notification for the following topics:

INVENTORY

A notification is sent when a listing is CREATED or UPDATED.

A listing can be retrieved using the GET /inventory/{id} endpoint.

PURCHASE

A notification is sent when a purchase is CREATED or UPDATED.

A purchase order can be retrieved using the GET /purchases/{id} endpoint.

INVOICE

A notification is sent when an invoice is CREATED or UPDATED.

An invoice can be retrieved using the GET /invoices/{id} endpoint

LINE

A notification is sent when a line is CREATED or UPDATED.

A line can be retrieved using the GET /lines/{id} endpoint

HOLD

A notification is sent when a hold is CREATED, UPDATED or DELETED.

A hold can be retrieved using the GET /holds/{id} endpoint

Events:

After a subscription is configured for an account using a topic, all the events related to that topic are sent as notifications when the account performs an action related to that topic.

The events are in the payload of the requests sent to the URL set in the subscription and they are as follows:

id	unique identifier of the instance to which the notification refers. The type of the instance and the endpoint that can be used to retrieve the instance details depend of the topic of the notification
accountId	account of the instance
topic	one of the accepted topics (INVENTORY, PURCHASE, INVOICE, LINE, HOLD)
action	action that generated the event (CREATED, UPDATED or DELETED, according to the topic)
generatedBySameAccount	whether or not the push notification you are receiving was authored by the same application through which you registered for the webhook
current	SkyBox entity in question (see topic for details) containing only the relevant fields - on UPDATE it will contain only differences found in relevant fields. Will be renamed according to topic in question (inventory, purchase, invoice, line, hold) - see examples below.
previous	SkyBox entity in question (see topic for details) containing only differences found in relevant fields. Only available on UPDATED actions

Examples

Example of usage

The following is an example of a subscription that will receive all notifications regarding Inventory changes.

1. Add a subscription sending a POST to https://skybox.vividseats.com/services/webhooks:

2. A user creates InventoryId 20, prompting a Webhook notification to be sent to https://example.com

3. A user or integrator made a price change on InventoryId 20, prompting a Webhook notification to be sent to https://example.com

4. A call to SkyBox to search the details of the relevant inventory (ID=20) should be made (if necessary):

Example of actions that fire events

Create a purchase with inventory lines and generic lines:

• One event with topic PURCHASE and action CREATED.

• One event per inventory line with topic INVENTORY and action CREATED.

• One event per inventory line with topic LINE and action CREATED.

• One event per generic line with topic LINE and action CREATED.

A split of a listing into 2 listings:

• One event with topic INVENTORY and action CREATED.

• One event with topic INVENTORY and action UPDATED for the split inventory.

A merge of 2 listings:

• One event with topic INVENTORY and action CREATED.

• One event with topic INVENTORY and action UPDATED for each inventory merged.

Create an invoice with inventory lines and generic lines:

• One event with topic INVOICE and action CREATED.

• One event per inventory line with topic LINE and action CREATED.

• One event per generic line with topic LINE and action CREATED.