Create subscriptions

Use POST URI/webhooks endpoint to subscribe to webhook events and receive timely notifications for events occurring within Tango. For instance, subscribing to the itemAvailability event ensures you receive notifications when a catalog item undergoes changes such as becoming temporarily unavailable, regaining availability at a later time, or being marked as deprecated. This capability enhances your system's responsiveness and keeps you informed of critical updates in real time. See our Supported webhook events.

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

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.

Example 1: Subscribe by Category Subscribe 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 '{
    "url": "https://your-domain.com/webhooks/tango",
    "categories": ["ITEM"],
    "signingCertificate": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."
  }'
`

Example 2: Subscribe by Event Type Subscribe to specific event types:

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

Example 3: Subscribe with Custom Authentication Headers Include custom headers for additional authentication:

curl --request POST \
  --url https://integration-api.tangocard.com/raas/v2/webhooks \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "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..."
  }'

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:

201 Created
400 Bad Request
401 Unauthorized

Important: Save the webhookId to manage, test, and delete your subscription.

Authenticating Tango's Webhook Calls to Your Endpoint

When you create a webhook subscription, you need to tell Tango how to authenticate when calling YOUR webhook endpoint. This is done through two parameters in the POST URI/webhooks request:

signingCertificate - Your X.509 public key (Tango uses this to sign payloads) headers - Custom headers that Tango will include in webhook requests

This section explains how to set up each authentication method.

Understanding the Authentication Parameters

When creating a webhook subscription, you configure two key parameters that tell Tango how to authenticate when calling your endpoint:

Parameter	Purpose	Required?
`signingCertificate`	Your X.509 public key - Tango uses this to sign the webhook payload	Highly Recommended
`headers`	Custom headers Tango will include in webhook requests to your endpoint	Optional

Let's walk through each authentication method step by step.

Method 1: RSA Signature Verification (RECOMMENDED)

This is the most secure method. You generate an RSA key pair, give Tango your public key, and verify signatures using your private key.

Step 1: Generate Your RSA Key Pair

# Generate 2048-bit private key
penssl genrsa -out private_key.pem 2048

# Extract public key from private key
openssl rsa -in private_key.pem -pubout -out public_key.pem

# View the keys
cat private_key.pem
cat public_key.pem

Your public_key.pem will look like this:

Step 2: Convert Public Key to Base64 (Single Line)

This is what customers struggle with! Tango needs the public key as a single-line base64 string WITHOUT the PEM headers.

# Remove headers and newlines - create single line
grep -v "BEGIN|END" public_key.pem | tr -d '\n' > public_key_base64.txt

# View the result
cat public_key_base64.txt

The output should be a single line like:

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu1SU1LfVLPHCozMxH2Mo4lgOEePzNm0tRgeLezV6ffAt0gunVTLw7onLRnrq0/IzW7yWR7QkrmBL7jTKEn5u+qKhbwKfBstIs+bMY2Zkp18gnTxKLxoS2tFczGkPLPgizskuemMghRniWaoLcyehkd3qqGElvW/VDL5AaWTg0nLVkjRo9z+40RQzuVaE8AkAFmxZzow3x+VJYKdjykkJ0iT9wCS0DRTXu269V264Vf/3jvredZiKRkgwlL9xNAwxXFg0x/XFw005UWVRIkdgcKWTjpBP2dPwVZ4WWC+9aGVd+Gyn1o0CLelf4rEjGoXbAAEgAqeGUxrcIlbjXfbcmwIDAQAB

Step 3: Subscribe with Your Public Key

# Read the base64 public key
PUBLIC_KEY=$(cat public_key_base64.txt)

# Create subscription with RSA signing certificate
curl --request POST \
  --url https://integration-api.tangocard.com/raas/v2/webhooks \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://your-domain.com/webhooks/tango",
    "eventTypes": ["ItemAvailability", "AccountStatus"],
    "signingCertificate": "'"$PUBLIC_KEY"'"
  }'

Method 2: Custom Headers (Simpler but Less Secure)

If RSA signature verification is too complex for your setup, you can use custom authentication headers. Tango will include these headers in every webhook request.

Common Custom Header Patterns Pattern 1: Simple Secret Token

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

Pattern 2: API Key Header

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

Pattern 3: Bearer Token

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

Pattern 4: Multiple Headers (Defense in Depth)

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

⚠️
Important: Managing OAuth 2.0 Tokens in Custom Headers

If you use an OAuth 2.0 access token in your custom headers (for Tango to authenticate to YOUR endpoint), you are responsible for maintaining a valid token. OAuth tokens typically expire after a set period (e.g., 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:

Monitor token expiration - Track when your OAuth tokens expire
Refresh tokens proactively - Get 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 Rotation

Scenario: Your webhook endpoint uses OAuth 2.0 for authentication. Tokens expire every 24 hours and must be rotated to maintain webhook connectivity.

Solution: Implement automated token rotation with webhook subscription updates.

Step 1: Subscribe with Initial OAuth Token

# 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 '{
    "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 Token Expires

# 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"'"
      }
    ]
  }'

Step 3: Automate Token Rotation (Recommended)