Supported webhook events

With the first release of the Tango wehbooks, we support the following events: item availability and account status. See how you can Create a subscription.

Subscribe to the following events in Tango API:

EventCategoryEventTypeDescription
Item availabilityITEMitemAvailabilitySends an event when the availability status of an item changes.
Account statusACCOUNTaccountStatusSends an event when the status of an account changes within the platform

All Event Payloads follow the following format:

PropertyTypeDescription
eventIdstringThe unique ID associated with the specific event
revisionlongThe position of the event within the subscription.
eventTypeeventTypeThe type of the event that occurred such as ItemAvailability, and AccountStatus'.
categoryeventCategoryThe event category you want to subscribe to, such as ITEM, and ACCOUNT.
eventOccurredAttimestampIncludes 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:

#StepsDescription
1Import catalog ItemsImports 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.
2Set up a webhook Event ListenerAcme sets up a webhook event listener to receive notifications whenever the itemAvailability event occurs.
3Integrate availability logic into the catalogAcme integrates the availability logic into its catalog management system, ensuring that it can dynamically process the event notification status change.
4Subscribe to the itemAvailability WebhookAcme subscribes to the Tango itemAvailability webhook using the POST /webhooks API endpoint.
5Process the event (Event Handling)When Acme receives an itemAvailability webhook notification, its system processes it.
6Update its dynamic catalogAcme 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.
7Display Real-time CatalogAs 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 statusDescription
AVAILABLEThis item is available for ordering.
DEGRADEDThis item is currently experiencing higher-than-usual errors. We are working to restore this item for you. We will have an update shortly.
UNAVAILABLEThis item is currently unavailable. We are working to restore this item for you. We will have an update for you shortly.
DEPRECATEDThis item is permanently unavailable.

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

Body ParamsTypeDescription
urlstringEnter the URL of your webhook listener. It must be a valid URL and this field is required.
categoriesarray of stringsEnter ITEM for categories. This field is optional if you're specifying eventTypes.
eventTypesarray of stringsEnter 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 ofitemAvailability: 

{
  "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:

StatusDescription
ActiveThe account is Active and you can conduct normal processing, funding, and placing orders.
InactiveThe 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.
DisabledYou 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.
FrozenYour 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.
DeletedThe 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 ParamsTypeDescription
urlstringEnter the URL of your webhook listener. It must be a valid URL and this field is required.
categoriesarray of stringsEnter ACCOUNT for categories. This field is optional if you're specifying eventTypes.
eventTypesarray of stringsEnter 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