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 Data Enrichment in the main navigation of your Pagos Service Panel, and click the Webhooks tab. You can return to this tab any time to review and edit existing webhooks, or add new webhooks as needed.
  • 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

​
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 
{
    "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 of the impacted network token to get the full updated details. 
{
    "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 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: 
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 
{
  x-pagos-signature: t=1731326247,v1=K1dEDpPNgRiehBEZzyx1/mZYKjE0jrK3qkvklPqAG+g=
  body:
  {
    "type":"wh_job_created",
    "data":{
      "job_id":23255,
      "timestamp":"2024-11-11T11:57:22.6315227Z",
      "merchant_id":"ae89c6af-dde7-4460-8a6f-bd64ec0826a6"
    }
  }
}
Python Code for Generating and Comparing Signatures 
import hmac
import hashlib
import base64

signature = 'K1dEDpPNgRiehBEZzyx1/mZYKjE0jrK3qkvklPqAG+g='
time_stamp = '1731326247'
message_body = '{"type":"wh_job_created","data":{"job_id":23255,"timestamp":"2024-11-11T11:57:22.6315227Z","merchant_id":"ae89c6af-dde7-4460-8a6f-bd64ec0826a6"}}'

message = time_stamp + '.' + message_body
secret_key = "RAJZ5nBM,)Ub]eUw7cXwD%]hN<tHIIYR#2%Tv[FS6Ad_[{y[;@#sh2<><8HrEd>r"

# 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}")
Webhook verification is highly recommended, but isn’t required. We also advise (but don’t require) you to allow-list the Pagos IP address that sends webhooks to your system as an additional security measure.