> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pagos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Network Tokenization Webhooks

Webhooks are a system of automated notifications that push information to your designated destination when important events occur. To create a webhook, click **Network Tokens** under **Card Network APIs** in the main navigation of your Pagos Service Panel, and click the [**Webhooks**](/card-network-apis/network-tokens#webhooks) tab. You can return to this tab any time to review and edit existing webhooks, or add new webhooks as needed.

<Note>
  * If a single webhook has five **consecutive** failures, we'll set the webhook status to *inactive*

  * If a webhook fails or is set to *inactive*, navigate to the **Webhooks** tab to edit and re-enable the webhook
</Note>

## Webhook Types

You'll receive webhook notifications from Pagos for the following events types:

### Token Status Updates

When the status of a network token changes, you'll receive a **networkTokenStatusUpdated** webhook containing the following information:

* Details about the token, including the token Ref ID, card brand, status (e.g. inactive, active, suspended, or deleted), and expiration date of the token (when the `status` is active). **Keep in mind,** this expiration date is the expiration date of the token, not the underlying PAN

* The `date` in UTC when the event was created, written in UNIX Epoch Timestamp format

* The `reason` for the event, provided the associated card brand included this detail

```json theme={null}
{
    "token_ref_id": "visa-cb9b0e653e5809db32caacc0205210ad",
    "card_network_name": "visa",
    "event_type": "networkTokenStatusUpdated",
    "date": 1661807833,
    "merchant_id": "c9a303b8-e812-4516-a0d2-cd90e56742b2"
    "status": "active",
    "expiration_date": {
      "year": "2023",
      "month": "12"
    },
    "reason": "",
    "metadata": "e2318ac9-56d2-4835-9b7a-d72369cc0e1b"
}
```

### Lifecycle Management Updates

When a network token has a lifecycle management (LCM) update—meaning the issuer updated details of the underlying PAN (e.g. last four digits, expiry date)—you'll receive a **networkTokenCardUpdated** webhook. This webhook will contain the token ID and card brand; you can then [request the status](#getting-the-status-of-a-network-token) of the impacted network token to get the full updated details.

```json theme={null}
{
    "token_ref_id": "visa-cb9b0e653e5809db32caacc0205210ad",
    "card_network_name": "visa",
    "event_type": "networkTokenCardUpdated",
    "date": 1661807833,
    "merchant_id": "c9a303b8-e812-4516-a0d2-cd90e56742b2"
    "metadata": "e2318ac9-56d2-4835-9b7a-d72369cc0e1b"
}
```

## Validating webhooks

When you first set up a webhook, you'll create a **SecretKey** for it. Save each SecretKey somewhere secure for use in validating webhooks from Pagos moving forward. We will not display your secret again; if you ever lose it, create a new one by editing the webhook in the [Network Tokenization](/card-network-apis/network-tokens#webhooks) page of your Pagos Service Panel.

The header of each webhook you receive includes a `x-pagos-signature` property containing an HMAC-SHA256 generated hash signature. We recommend always validating this signature to ensure your server only processes webhook deliveries sent by Pagos and to verify the delivery hasn't been tampered with. This will help you avoid using server resources to process deliveries, or updating your source-of-truth systems based on messages that do not originate from Pagos, thereby helping to prevent man-in-the-middle attacks.

The `x-pagos-signature` contains the webhook signature in the following format:

```bash theme={null}
x-pagos-signature: t={timestamp in unix time},{signature-version}={signature}
```

Pagos generates the webhook signature hash as a concatenation of the timestamp value in `t=` from the `x-pagos-signature`, a period (“.”), the contents of the `body:` of the webhook payload, and the stored customer secret. This signature will be sent in the  `{signature-version}=` property of the `x-pagos-signature`. The `{signature-version}` will be initially set as “V1”, representing SHA256. If additional hashing algorithms are offered, then an additional `{signature-version}` will be created representing these additional hashing algorithms.

To validate the webhook signature a customer should generate a webhook signature using the above process of concatenation of the timestamp value in `t=` from the `x-pagos-signature` plus a period “.”  plus the contents of the `body:` of the webhook payload and the stored customer secret. Then compare your signature with the signature value in `{signature-version}={signature}`. If they match, you're safe to process the webhook. If they don’t match, then the webhook should be dropped.

**Example Webhook Message**

```json theme={null}
{
  x-pagos-signature: t=1765930794,v1=EAu4daJPdJOOFJiEBe/76s2g7gXAybX9sriFh8imlAA=
  body:
  {
    "token_ref_id": "visa-d5c4391ac52d493f4fd9d5b2206cd2a8",
    "card_network_name": "visa",
    "event_type": "networkTokenCardUpdated",
    "date": "1765930794",
    "metadata": null,
    "merchant_id": "8962ebe6-1ac5-4ce2-979f-6d5936e85614"
  }
}
```

**Python Code for Generating and Comparing Signatures**

```python theme={null}
import hmac
import hashlib
import base64

signature = 'EAu4daJPdJOOFJiEBe/76s2g7gXAybX9sriFh8imlAA='
time_stamp = '1765930794'
message_body = '{"token_ref_id":"visa-d5c4391ac52d493f4fd9d5b2206cd2a8","card_network_name":"visa","event_type":"networkTokenCardUpdated","date":"1765930794","metadata":null,"merchant_id":"8962ebe6-1ac5-4ce2-979f-6d5936e85614"}'

message = time_stamp + '.' + message_body
secret_key = "9861298ewrlkhsadfoipyasdpo83h2jk1;kd;'lksdpouih;sdf"

# Create an HMAC object using SHA-256
hmac_object = hmac.new(secret_key.encode('utf-8'), message.encode('utf-8'), hashlib.sha256)

# Get the HMAC signature as a hexadecimal string
base64_string = base64.b64encode(hmac_object.digest()).decode("utf-8")

result = base64_string == signature

print(f"The signatures match: {result}")
```

<Note>
  Webhook verification is highly recommended, but isn't required. We also advise (but don't require) you to allow-list the [Pagos IP address](/getting-started/pagos-domains-and-ip-addresses#account-updater-and-network-tokenization-ip-addresses) that sends webhooks to your system as an additional security measure.
</Note>