Create webhook subscriptions

Use the following endpoint to subscribe to webhook events and receive real-time notifications from Tango. For example, subscribing to the itemAvailability event allows you to detect when a catalog item becomes unavailable, returns to stock, or is deprecated.

This capability enhances your system's responsiveness and keeps you informed of critical updates in real time. See our Supported webhook events.

Endpoint

Use the following endpoint to create webhook subscriptions:

Endpoint	Purpose
`POST {URI}/webhooks`	To create a subscription

Parameters

Here are the parameters used with POST URI/webhooks to create a subscription to events on your platform:

Body params	Data type	Requirement	Description
url	string	required	Your HTTPS webhook listener URL
headers	array of objects		Custom headers for authentication
headers[].name	string	Conditional	Header name (required if using headers)
headers[].value	string	Conditional	Header value (required if using headers)
categories	array[string]	Conditional	The categories the customer wants to subscribe to. Optional if specifying eventTypes.
eventTypes	array[string]	Conditional	The event types the customer wants to subscribe to. Optional if specifying categories.
signingCertificate	string	Conditional	The public X.509 Base64-encoded public key (single line, no PEM headers) used to sign the webhook payload. Required when the authentication method is RSA, ECDSA, EdDSA, or DSA. The following rules apply to signingCertificate: Must contain a single-line Base64 string. Must not include PEM headers (-----BEGIN PUBLIC KEY----- / -----END PUBLIC KEY-----). Must have no line breaks (not wrapped at 64 characters). Can include RSA 2048-bit keys.
hmacSharedSecretKey	string	Conditional	The HMAC secret key used to sign the webhook payload. Required when `payloadVerificationMethod` is HMAC. The key must be base64 encoded.
payloadVerificationMethod	enum	Conditional	Method to verify webhook payload authenticity

Subscription examples

The following list includes multiple examples showing how to create different types of subscriptions. See steps on how to Generate signing certificate or Hmac Shared Secret Key.

Subscribe by category

This example shows how to subscribe your webhook endpoint to all events within the ITEM category:

curl --request POST \
  --url https://integration-api.tangocard.com/raas/v2/webhooks \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "payloadVerificationMethod": "X509",
    "url": "https://your-domain.com/webhooks/tango",
    "categories": ["ITEM"],
    "signingCertificate": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."
  }'
`

Subscribe by Event Type

This example subscribes only to specific event types such as itemAvaliability, rather than a whole category:

curl --request POST \
  --url https://integration-api.tangocard.com/raas/v2/webhooks \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "payloadVerificationMethod": "X509",
    "url": "https://your-domain.com/webhooks/tango",
    "eventTypes": ["ItemAvailability", "AccountStatus"],
    "signingCertificate": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."
  }'

Subscribe with Custom Authentication Headers

This example adds custom headers to your webhook request, in addition to the X.509, for additional authentication. The headers added in this example are: X-Webhook-Secret: "your-secret-key-here" and X-API-Key: "your-api-key-here". These headers are included in Tango's webhook for verification:

curl --request POST \
  --url https://integration-api.tangocard.com/raas/v2/webhooks \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "payloadVerificationMethod": "X509",
    "url": "https://your-domain.com/webhooks/tango",
    "headers": [
      {
        "name": "X-Webhook-Secret",
        "value": "your-secret-key-here"
      },
      {
        "name": "X-API-Key",
        "value": "your-api-key-here"
      }
    ],
    "eventTypes": ["ItemAvailability"],
    "signingCertificate": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."
  }'

Subscribe with `PayloadVerificationMethod` X509

This example shows how you can create a webhook subscription that uses X.509 certificate for payload signing. Tango will use this certificate to sign all webhook payloads it sends to your endpoint. See Webhook signature authentication (X509).

curl -X POST https://integration-api.tangocard.com/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic YOUR_BASIC_AUTH_TOKEN" \
  -d '{
    "url": "https://your-webhook-endpoint.com/webhook",
    "headers": [],
    "categories": [],
    "eventTypes": ["AsyncOrderStatus"],
    "payloadVerificationMethod": "X509",
    "signingCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURD..."
  }'

Subscribe with `PayloadVerificationMethod` HMAC

This example shows how to create a webhook subscription where all webhook payloads sent to your endpoint are signed using HMAC. HMAC is shared secret key to show the payload has really come from the provider. See Webhook signature authentication (HMAC).

curl -X POST https://integration-api.tangocard.com/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic YOUR_BASIC_AUTH_TOKEN" \
  -d '{
    "url": "https://your-webhook-endpoint.com/webhook",
    "headers": [],
    "categories": [],
    "eventTypes": ["AsyncOrderStatus"],
    "payloadVerificationMethod": "HMAC",
    "hmacSharedSecretKey": "dGhpc2lzYXNlY3VyZTMyYnl0ZXNlY3JldGtleWZvcmhtYWNzaGEyNTY="
  }'

Subscribe with OAuth and `PayloadVerificationMethod` NONE

This example shows how to create a webhook subscription where all webhook payloads sent to your endpoint authenticate using OAuth2.0.

curl --request POST \
  --url https://integration-api.tangocard.com/raas/v2/webhooks \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "payloadVerificationMethod": "NONE",
    "url": "https://your-domain.com/webhooks/tango",
    "eventTypes": ["AccountStatus"],
    "headers": [
      {
        "name": "Authorization",
        "value": "Bearer my_internal_webhook_token_xyz"
      }
    ]
  }'

Subscribe with `PayloadVerificationMethod` NONE

If you do not require payload signing, set payloadVerificationMethod to NONE. No signingCertificate or hmacSharedSecretKey should be provided. No signature header will be included in webhook deliveries for these subscriptions. See No payload verification (NONE).

curl -X POST https://integration-api.tangocard.com/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic YOUR_BASIC_AUTH_TOKEN" \
  -d '{
    "url": "https://your-webhook-endpoint.com/webhook",
    "headers": [],
    "categories": [],
    "eventTypes": ["AsyncOrderStatus"],
    "payloadVerificationMethod": "NONE"
  }'

Payload response

On successful subscription, you'll receive:

{
  "webhookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "expiresAt": "2024-06-13T19:01:16.536Z"
}

The possible response codes for this endpoint are as follows. For details, see i18nkey codes and their error messages:

Response code	Meaning
201	New resource has been successfully created as a result of the request.
400	The server could not understand the request due to invalid syntax.
401	Authentication is required and has either not been provided or failed.

Maintain your subscription

If your webhook uses OAuth tokens for authentication, you must keep those tokens up to date to ensure webhook deliveries continue successfully.

📘
Note:
If you use an OAuth 2.0 access token in custom headers (for Tango to authenticate to your endpoint), you are responsible for maintaining a valid token.

OAuth tokens expire after a defined period (e.g., 5 minutes, 1 hour, 24 hours, or 30 days, depending on your OAuth provider). When a token expires, Tango's webhook calls to your endpoint will fail with 401 Unauthorized errors.

Your Responsibilities:

To avoid disruptions, you must:

Monitor token expiration: Track when your OAuth tokens expire
Refresh tokens proactively: Generate new tokens before expiration
Update webhook subscription: Use PATCH URI/webhooks/{webhookId} to update headers with the new token
Avoid service disruptions: Don't let tokens expire without updating

Use Case: OAuth token totation

Your webhook endpoint uses OAuth 2.0 for authentication. Tango continues sending webhook events over time. But your OAuth tokens expire after either 24 hours or 5 minutes, depending on the audience specified when creating the token. When the token expires, your endpoint will reject incoming requests, Tango receives a 401 Unauthorized response, and webhook delivery fails.

You must continuously refresh and update the token stored in your webhook subscription to maintain webhook connectivity. Implement automated token rotation with webhook subscription updates in two steps:

Step 1: Create a subscription with the initial OAuth token

Get an OAuth token from your auth provider and include it in the webhook headers when creating the subscription. Tango stores this token and uses it for outgoing webhook requests:

# Get your OAuth token from your auth provider
YOUR_OAUTH_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Create webhook subscription with OAuth token
curl --request POST \
  --url https://integration-api.tangocard.com/raas/v2/webhooks \
  --header 'Authorization: Bearer YOUR_TANGO_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "payloadVerificationMethod": "NONE",
    "url": "https://your-domain.com/webhooks/tango",
    "eventTypes": ["ItemAvailability", "AccountStatus", "RewardStatus"],
    "signingCertificate": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
    "headers": [
      {
        "name": "Authorization",
        "value": "Bearer '"$YOUR_OAUTH_TOKEN"'"
      }
    ]
  }'

# Response includes webhookId - SAVE THIS!
# {
#   "webhookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
#   "expiresAt": "2026-02-13T19:01:16.536Z"
# }

Step 2: Update subscription when the token expires

Generate a new token before the token expires, then call PATCH/webhooks/{WebhookID}. At the end, update the Authorization header with the new token:

# Get new OAuth token from your auth provider
NEW_OAUTH_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...NEW_TOKEN..."

# Update webhook subscription with new token
WEBHOOK_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"

curl --request PATCH \
  --url https://integration-api.tangocard.com/raas/v2/webhooks/$WEBHOOK_ID \
  --header 'Authorization: Bearer YOUR_TANGO_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "headers": [
      {
        "name": "Authorization",
        "value": "Bearer '"$NEW_OAUTH_TOKEN"'"
      }
    ]
  }'

📘
Best practices:

Set up automated token refresh before expiration

Monitor token expiration and renewal processes

Consider using refresh tokens for seamless rotation

See Payload verification method field rules.

Endpoint

Parameters

Subscription examples

Subscribe by category

Subscribe by Event Type

Subscribe with Custom Authentication Headers

Subscribe with PayloadVerificationMethod X509

Subscribe with PayloadVerificationMethod HMAC

Subscribe with OAuth and PayloadVerificationMethod NONE

Subscribe with PayloadVerificationMethod NONE

Payload response

Maintain your subscription

Note:

Your Responsibilities:

Use Case: OAuth token totation

Best practices:

Subscribe with `PayloadVerificationMethod` X509

Subscribe with `PayloadVerificationMethod` HMAC

Subscribe with OAuth and `PayloadVerificationMethod` NONE

Subscribe with `PayloadVerificationMethod` NONE