Batch Account Updater Webhooks

Webhooks are a system of automated notifications that push information to your designated destination when important events occur. To create a webhook, click Account Updater 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.

​

Webhook Types

You will receive the following types of webhook notifications from Pagos when a job status changes:

​

Job Created

This notification alerts you that the job was successful; the webhook includes an associated job_id.

{
  "type": "wh_job_created",
  "data": {
    "merchant_id": "9bb8592c-cb99-48f7-907e-f97de930fc5c",
    "job_id": 98765,
    "timestamp": "2025-01-25T23:37:21.6882095Z"
  }
}

​

Job Complete

This notification alerts you that the job was successful.

{
  "type": "wh_job_completed",
  "data": {
    "merchant_id": "9bb8592c-cb99-48f7-907e-f97de930fc5c",
    "job_id": 98765,
    "timestamp": "2025-01-25T23:37:21.6882095Z"
  }
}

​

Job Failed

This notification alerts you that the job was not successful. This webhook includes a metadata property in the data.error_details [] array that contains the value of the metadata for the row in the submitted job file that produced the error.

{
  "type": "wh_job_failed",
  "data": {
    "merchant_id": "9bb8592c-cb99-48f7-907e-f97de930fc5c",
    "job_id": 54321,
    "reason": "validation_failed",
    "error_details": [
      {
        "detail": "file_validation_year_invalid",
        "additional_info": "Row = 911, Reason = Invalid length of a expiry_year"
        "metadata": "[value from the job file for the row]"
      }
    ],
    "timestamp": "2025-01-25T23:37:21.6882095Z"
  }
}

Learn more about this webhook in our error handling guide.

​

Network Unprocessable

This notification identifies when a network MID has not been configured for the calling merchant. Contact your Pagos Account Manager for assistance.

{
  "type": "wh_network_unprocessable",
  "data": {
    "merchant_id": "9bb8592c-cb99-48f7-907e-f97de930fc5c",
    "job_id": 54321,
    "network": "SampleNetwork",
    "cards_amount": 10,
    "timestamp": "2025-01-25T23:37:21.6882095Z"
  }
}

​

Network Processed

This notification identifies which card brand was successfully processed.

{
  "type": "wh_network_processed",
  "data": {
    "merchant_id": "9bb8592c-cb99-48f7-907e-f97de930fc5c",
    "network": "visa",
    "job_id": 12345,
    "timestamp": "2025-01-25T23:37:21.6882095Z"
  }
}

​

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 Account Updater 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}")