Update a subscription

Use PATCH {URI}/webhooks/{webhookId} to update an existing webhook subscription. This flexibility ensures that your subscription remains adaptable to evolving integration requirements. PATCH is an http method used to apply partial modifications to a resource, while {URI} is a placeholder for the base URI of the API you are working with. Replace {webhookId} with the unique identifier of the webhook.

Endpoint	Purpose
`PATCH {URI}/webhooks/{webhookId}`	To update an existing subscription

You can use this endpoint to update various properties of the webhook, such as the endpoint URL, event types, or other settings. The path parameter {webhookId} is used to specify the unique identifier of the webhook you want to update:

Parameter	Data type	Requirement	Description
webhookId	string	required	The webhook identifier

When using the PATCH {URI}/webhooks/{webhookId} endpoint to update an existing webhook, you can include various body parameters to specify the changes you want to make:

Parameter	Data type	Requirement	Description
url	string		URL to which the webhook should send events. Must be a valid URL.
headers	array of objects		Appropriate for the authentication method the customer wants Tango to use when calling their webhook listener
-name	string	required	The name of the header
-value	string	required	The value of the header
Categories	array of objects		The categories the customer wants to subscribe to.
eventTypes	array of objects		The event types the customer wants to subscribe to. It shows the event types that the webhook should listen for.
signingCertificate	string	optional	The public X509 certificate used to sign the webhook payload. The certificate must be base64 encoded.
hmacSharedSecretKey	string	optional	The HMAC secret key used to sign the webhook payload. Required when `payloadVerificationMethod` is HMAC. The key must be base64 encoded.
payloadVerificationMethod	enum	optional	Method to verify webhook payload authenticity. Allowed Values are: HMAC, X509, NONE

The following response shows an example of how to modify a webhook subscription by using PATCH {URI}/webhooks/{webhookId}:

{
  "webhookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "string",
  "headers": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "categories": [
    "string"
  ],
  "eventTypes": [
    "string"
  ],
  "signingCertificate": "string",
  "hmacSharedSecretKey": "string",
  "payloadVerificationMethod": "string" //HMAC, X509, NONE
  "createdAt": "2024-06-13T20:06:24.565Z",
  "expiresAt": "2024-06-13T20:06:24.565Z",
  "updatedAt": "2024-06-13T20:06:24.565Z"
}

Switch verification methods on a subscription

When updating a subscription via PATCH {URI}/webhooks/{webhookId}:

Stay on the same payloadVerificationmethod

You only need to provide the updated field—no need to specify payloadVerificationMethod. For example, rotate an X509 certificate or refresh HMAC key.

Example: Rotating X.509 Certificate

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

Example: Rotating HMAC Shared Secret

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

Switch to a new payloadVerificationmethod

You must specify the new payloadVerificationMethod. For example, from X509 to HMAC, or from HMAC to NONE.

Example: Switching from X509 to HMAC

curl -X PATCH https://integration-api.tangocard.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: Switching from HMAC to X509


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

Example: Disabling Payload Verification

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

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

200 OK
400 Bad Request
401 Unauthorized