Webhook authentication and verification overview

When you create a webhook subscription, you must specify how Tango should prove that each webhook request truly comes from Tango and not from an unauthorized source. Tango supports two independent mechanisms for authenticating webhook deliveries, both configured through the POST {URI}/webhooks request:

• Tango signs the webhook payloads using your public key
• Tango includes one or more custom authentication headers

Authentication parameters

Payload verification methods

Webhook payload verification ensures that the event has been originated from our platform and the message body has not been modified in transit. Only authorized systems can successfully send webhook requests. Verification prevents spoofing, tampering, and replay attempts. The sections below explain the different verification and authentication methods you can use to secure your webhook endpoint:

• Overview: Payload verification methods
• Endpoint Authorization (Basic Auth or OAuth)
• Backward Compatibility
• Switching Between Verification Methods

Overview: payload verification methods

We support the following payload verification methods via the payloadVerificationMethod field:

📘

Best practices:

We strongly recommend using X509 over HMAC. X509 uses asymmetric cryptography—your private key stays with you, and only your public certificate is shared. HMAC requires sharing a secret with both sides, which increases exposure risk.

Payload verification method field rules

When creating a Tango webhook subscription, you must choose one authentication method. Each method has strict rules about which fields can be included in your request:

Backward compatibility behavior

The payloadVerificationMethod field is optional for existing integrations. If it is omitted, Tango infers behavior based on other fields:

Existing subscriptions created with only a signingCertificate will continue to work without change.

Switching verification methods

When managing webhook subscriptions, you may need to update or rotate the authentication materials used to verify incoming webhook requests. Tango allows you to change verification settings using the PATCH {URI}/webhooks/{webhookId} endpoint. There are two scenarios to consider:

A. Staying on the same verification method: (e.g., updating an X.509 certificate or rotating an HMAC key).

B. Switching to a different verification method: (e.g., moving from X509 to HMAC, or from HMAC to NONE).

A. Staying on the same method

If you are not changing the verification method itself, you only need to provide the updated field. You do not need to resend or modify payloadVerificationMethod. Tango will retain the existing method.

Example 1: Rotating an X.509 Certificate

In this example, the subscription continues using X509 as the verification method. Only the certificate is replaced and no other fields (including payloadVerificationMethod) are required.

curl -X PATCH https://api.example.com/subscriptions/{subscription-id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic YOUR_API_AUTH_TOKEN" \
  -d '{
    "signingCertificate": "NEW_BASE64_ENCODED_CERTIFICATE"
  }'

Example 2: Rotating HMAC Shared Secret

If you are staying on the HMAC verification method but need to replace your shared secret key (for example, during scheduled key rotation or when retiring an old key), you can update the subscription using PATCH. You only need to provide the new Base64‑encoded secret key—do not resend or modify payloadVerificationMethod.

curl -X PATCH https://api.example.com/subscriptions/{subscription-id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic YOUR_API_AUTH_TOKEN" \
  -d '{
    "hmacSharedSecretKey": "NEW_BASE64_ENCODED_SHARED_SECRET_KEY"
  }'

B. Switching to a new verification method

If you want to change the verification method used for webhook payloads (for example, moving from X509 to HMAC, HMAC to X509, or disabling verification entirely), you must explicitly set the new payloadVerificationMethod in your PATCH request. Unlike simple key rotation, switching methods always requires declaring the new method and supplying the correct authentication fields for that method.

Example 1: Switching from X509 to HMAC

In this transition, you are replacing certificate‑based signing with HMAC‑SHA256 signing. You must include payloadVerificationMethod: "HMAC" and a new Base64‑encoded shared secret (hmacSharedSecretKey).

curl -X PATCH https://api.example.com/subscriptions/{subscription-id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic YOUR_API_AUTH_TOKEN" \
  -d '{
       "payloadVerificationMethod": "HMAC",
       "hmacSharedSecretKey": "NEW_BASE64_ENCODED_SHARED_SECRET_KEY"
  }'

Example 2: Switching from HMAC to X509

To switch from HMAC signing to certificate‑based signing, provide: payloadVerificationMethod: "X509" and your Base64‑encoded public certificate (signingCertificate).

curl -X PATCH https://api.example.com/subscriptions/{subscription-id} \
  -H "Content-Type: application/json" \
  -d '{
    "payloadVerificationMethod": "X509",
    "signingCertificate": "NEW_BASE64_ENCODED_CERTIFICATE"
  }'

Example 3: Disabling Payload Verification (switch to NONE)

If you intentionally choose to remove all signature verification—not recommended unless you implement your own validation—you must explicitly set: payloadVerificationMethod: "NONE"

curl -X PATCH https://api.example.com/subscriptions/{subscription-id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic YOUR_API_AUTH_TOKEN" \
  -d '{
    "payloadVerificationMethod": "NONE"
  }'

Endpoint Authorization

In addition to payload signing, you can protect your webhook endpoint with an authorization header that Tango will include when delivering webhooks (for example, Basic auth, API key headers, or OAuth 2.0 bearer tokens).

For implementation details and curl examples, see Implementing Webhook Authentication.