Supported webhook events

With the first release of the Tango wehbooks, we support the following events: ItemAvailability and AccountStatus. See how you can Create a subscription.

Subscribe to the following events in Tango API:

Event	Category	EventType	Description
Item availability	`ITEM`	`ItemAvailability`	Sends an event when the availability status of an item changes.
Account status	`ACCOUNT`	`AccountStatus`	Sends an event when the status of an account changes within the platform

All Event Payloads follow the following format:

Property	Type	Description
`eventId`	string	The unique ID associated with the specific event
`revision`	long	The position of the event within the subscription.
`eventType`	eventType	The type of the event that occurred such as `ItemAvailability`, and `AccountStatus'`.
`category`	eventCategory	The event category you want to subscribe to, such as `ITEM`, and `ACCOUNT`.
`eventOccurredAt`	timestamp	Includes the timestamp of the event.

Item availability

Tango supports item availability. Item availability is a valuable resource, as it determines the availability of catalog items as they fluctuate. Subscribing to the ItemAvailability event type ensures you receive timely notifications when an item becomes unavailable or deprecated. Additionally, this event notification informs you when the item is available for purchase again. To learn more, check out our use case for dynamic catalog.

Use Case: Dynamic catalog

Acme, a wellness incentive company, wants to optimize its incentive reward catalog display by showing items only when they are available for redemption. They plan to achieve this dynamic catalog management using the Tango ItemAvailability webhook. To achieve the above goal, Acme follows the steps below:

To achieve the above goal, Acme makes sure to follow the steps below:

#	Steps	Description
1	Import catalog Items	Imports its catalog items into its system, including the utid and other relevant product details using the GET {URI}/catalogs API endpoint. All items are initially marked as AVAILABLE.
2	Set up a webhook Event Listener	Acme sets up a webhook event listener to receive notifications whenever the ItemAvailability event occurs.
3	Integrate availability logic into the catalog	Acme integrates the availability logic into its catalog management system, ensuring that it can dynamically process the event notification status change.
4	Subscribe to the IitemAvailability Webhook	Acme subscribes to the Tango ItemAvailability webhook using the POST /webhooks API endpoint.
5	Process the event (Event Handling)	When Acme receives an ItemAvailability webhook notification, its system processes it.
6	Update its dynamic catalog	Acme dynamically updates its online catalog based on the received webhook notifications. If an item is marked as AVAILABLE in the webhook event, it is displayed in the catalog. If it becomes UNAVAILABLE, DEGRADED, or DEPRECATED, the item is removed from the catalog or marked as out of stock depending on Acme’s business rules.
7	Display Real-time Catalog	As a result of this integration, Acme customers always see an up-to-date catalog, showing only those items that are currently available for redemption.

Benefits of dynamic catalog

By leveraging Tango ItemAvailability, you can achieve a dynamic and customer-centric catalog management system that benefits both your customers and business operations. Here are some of the benefits you are getting with ItemAvailability:

Enhanced Customer Experience: Customers see a catalog that accurately reflects the availability of products in real-time, reducing frustration caused by out-of-stock items.
Optimized Transactions: Acme can optimize its experience by only displaying items that are ready for redemption, potentially increasing conversion rates.
Reduced Manual Effort: Manual catalog management is minimized since ItemAvailability status is automatically updated based on webhook notifications.
Catalog Management: Acme gains better control over its catalog as items are added or removed as they become available or unavailable.

You can subscribe to the ItemAvailability events to be notified when an item status changes in your catalog. The following statuses are available for item availability which are returned byeventData.status:

Availability status	Description
`AVAILABLE`	This item is available for ordering.
`DEGRADED`	This item is currently experiencing higher-than-usual errors. We are working to restore this item for you. We will have an update shortly.
`UNAVAILABLE`	This item is currently unavailable. We are working to restore this item for you. We will have an update for you shortly.
`DEPRECATED`	This item is permanently unavailable.

When creating a subscription for item availability, use POST {URI}/webhooks and enter the following values:

Body Params	Type	Description
url	string	Enter the URL of your webhook listener. It must be a valid URL and this field is required.
categories	array of strings	Enter `ITEM` for categories. This field is optional if you're specifying eventTypes.
eventTypes	array of strings	Enter `ItemAvailability` for `eventTypes`. This field is optional if you're specifying categories.

The following example is a response payload of ItemAvailability:

Here is a response payload of ItemAvailability: 

{
  "eventId": "2e3b91ba-4d6a-43b5-8e77-3b31e3f938b3",
  "revision": 4,
  "category": "ITEM",
  "eventType": "ItemAvailability",
  "eventOccurredAt": "2024-06-17T17:10:00.759273600Z",
  "eventData": {
    "utid": "U275066",
    "status": "UNAVAILABLE"
  }
}

The following response messages are supported by webhook endpoints in Tango API:

200 Successful
400 Bad Request
401 Unauthorized
403 Forbidden
409 Conflict, Duplicate Exist

Account status

Tango supports sending events when any customer account on your platform changes status to Inactive, disabled, frozen, deleted or active. To subscribe to AccountStatus events, create a subscription with thePOST {URI}/webhooks and then select AccountStatus for eventType and ACCOUNTS for category.

Use case: account status

Acme, a wellness incentive company, would like to get notified whenever one of their customer accounts changes status in Tango. For example, when their account freezes, they would like to know immediately so they can take the necessary actions.

To achieve this goal and to stay on top, Acme subscribes to AccountStatus event using POST {URI}/webhooks and receives notification whenever one of their customer accounts is frozen, disabled, inactive, or active again.

Account statuses

The following account statuses are available with the AccountStatus subscription:

Status	Description
Active	The account is Active and you can conduct normal processing, funding, and placing orders.
Inactive	The account is Inactive and you cannot fund or place orders. Unlike Disabled account, you cannot change the Inactive status. For example, an internal request to close a platform/account(s). Contact your Customer Success Manager (CSM) at [email protected] for questions or help.
Disabled	You can set your account to Disable without any assistance from Tango. Once your account is disabled, no transactions are allowed. For example, you can temporarily disable your seasonal account to prevent any order/funding activity outside the designated time, or you can take your account offline for auditing purposes. You can also disable an account when you want to determine its status.
Frozen	Your account has reached the velocity threshold. No transaction can be done until the freeze is lifted by Tango. Contact your Customer Success Manager (CSM) at [email protected] for questions or help.
Deleted	The account is deleted and does not exist anymore.

When creating a subscription for account status, use POST {URI}/webhooks and enter the following values:

Body Params	Type	Description
url	string	Enter the URL of your webhook listener. It must be a valid URL and this field is required.
categories	array of strings	Enter `ACCOUNT` for categories. This field is optional if you're specifying eventTypes.
eventTypes	array of strings	Enter `AccountStatus` for eventTypes. This field is optional if you're specifying categories.

Here is a response payload of AccountStatus:

{
  "eventId": "45a2ddda-a159-42aa-a3ec-2f7b206a8495",
  "revision": 6,
  "category": "ACCOUNT",
  "eventType": "AccountStatus",
  "eventOccurredAt": "2024-06-17T20:31:19.852635900Z",
  "eventData": {
    "identifier": "A28448941",
    "status": "INACTIVE"
  }
}

The following response messages are supported by webhook endpoints in this release:

200 Successful
400 Bad Request
401 Unauthorized
403 Forbidden
409 Conflict, Duplicate Exist