Token update notifications

Configure a webhook to receive Network Token update notifications.

Use this service to get notified whenever something on the Network Token or it's underlying PAN changes. It pushes an HTTP message to a webhook of your choice and updates the card data mapped to the alias value stored in your token vault.

More specifically, a Token status request will be sent whereas the following parameters will be updated as soon as the respective card network triggers a change.

    "alias": "7LHXscqwAAEAAAGLgKAf-F9X1QGrAHsa",
    "fingerprint": "F-f5AcNienVUz735BKis71pD",
    "type": "CARD",
    "masked": "489537xxxxxx6386",
    "dateCreated": "2023-07-30T12:47:39Z",
    "card": {
        "panRemoved": false,
        "expiryMonth": "05",
        "expiryYear": "25",
        "cardInfo": {
            "brand": "VISA",
            "type": "debit",
            "usage": "consumer",
            "country": "US",
            "issuer": "U.S. REGION",
            "accountType": "PAN"
        "networkToken": {
            "expiryMonth": "05",
            "expiryYear": "25",
            "status": "ACTIVE",
            "paymentAccountReference": "V0010013020217426481676671969"
        "last4": "6386"
last4The last four digits of the underlying PAN.
card.expiryMonthThe expiry month of the underlying PAN.
card.expiryYearThe expiry year of the underlying PAN.
networkToken.statusThe status of the underlying PAN.
paymentAccountReferenceThe payment account reference number of the underlying PAN.
networkToken.expiryMonthThe expiry month of a Network Token.
networkToken.expiryYearThe expiry year of a Network Token.


Please contact us if you are missing a parameter.


To enable Network Token update notifications and to configure your webhook please login to your account. Navigate to the Network Tokenization section tab within the Settings menu on your project and add the endpoint url.

Additional security - webhook signing

To protect our webhooks from being tampered, add an additional security layer by signing our webhooks. To access your HMAC key sign, login to our dashboard and navigate to the API Keys tab in the Developers menu within the project section. PCI Proxy will use this key to calculate a signature and add two parameters within the HTTP request header request-signature: A unique timestamp t and the expected signature s0.

To calculate the expected signature, concatenate the timestamp as a string with the webhook payload. Convert the resulting string to bytes and finally create a signature with your HMAC key using SHA256. Finally, compare your calculation to the expected signature s0. If your calculated signature equals s0, the webhook payload is valid and was not modified.

// hex bytes of the key
byte[] key = Hex.decodeHex(key);

// Create sign with timestamp and payload
String algorithm = "HmacSha256";
SecretKeySpec macKey = new SecretKeySpec(key, algorithm);
Mac mac = Mac.getInstance(algorithm);
byte[] result = mac.doFinal(payload.getBytes());
String sign = Hex.encodeHexString(result);
# hey bytes of the key
key_hex_bytes = bytes.fromhex(key)

# Create sign with timestamp and payload
sign =, bytes(str(timestamp) + payload, 'utf-8'), hashlib.sha256)
# Create sign with timestamp and payload
echo hash_hmac('sha256', $timestamp . $payload, hex2bin($key));

To verify if you calculated the signature in the right way, the example below can be used. When testing locally, beware of pretty formatting the webhook payload, as it will result in a different signature than expected.

Given the key:

Given the payload:

Given the timestamp:

Then the signature is:


Retries are done max. 10 times with an exponential backoff until we receive an HTTP 2xx status code.