> ## 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.

# 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 **Card Network APIs** in the main navigation of your Pagos Service Panel, and click the [**Webhooks**](/card-network-apis/account-updater#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 will set the webhook status to *inactive*. This only happens if the failures are consecutive (not intermittent)

  * 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 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`.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/account-updater/batch-error-handling#webhook-error-notifications) 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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/card-network-apis/account-updater#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=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**

```python theme={null}
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}")
```

<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>