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:
| 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 itemAvailability 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 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:
| 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
Updated 15 days ago