Create webhook 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.
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.

Example 1: 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..."
  }'
`

Example 2: 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..."
  }'

Example 3: 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..."
  }'

Example 4: 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..."
  }'

Example 5: 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="
  }'

Example 6: 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"
      }
    ]
  }'

⚠️
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 '{
    "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 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"'"
      }
    ]
  }'

Example 7: 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:

201 Created
400 Bad Request
401 Unauthorized

See Payload verification method field rules.