> For the complete documentation index, see [llms.txt](https://docs.pagsmile.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pagsmile.com/reference/remittance-api/business/webhook/webhook-common.md).

# Webhook Common

**Notification delivery**

Pagsmile sends an HTTP `POST` request to the webhook URL configured for your integration.

**Content-Type:** `application/json; charset=UTF-8`

All Remittance API notifications use the envelope below.

{% hint style="info" %}
**Requirement:** `M` = Mandatory, `O` = Optional, and `C` = Conditional. A conditional field is mandatory only when the condition stated in its description applies.
{% endhint %}

**Notification body**

**Notification envelope fields**

| Field         | Type    | Requirement | Description                                                                                                                                                                                               |
| ------------- | ------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `partner_id`  | string  | O           | Pagsmile-assigned unique identifier of the partner.                                                                                                                                                       |
| `timestamp`   | string  | M           | <p>Date and time when the notification was generated.<br>Format: <code>yyyy-MM-dd HH:mm:ss</code>.</p>                                                                                                    |
| `version`     | string  | M           | <p>Remittance API webhook protocol version.<br>Fixed value: <code>1.0</code>.</p>                                                                                                                         |
| `random_key`  | string  | O           | Reserved field used for the encrypted AES key when payload encryption is enabled.                                                                                                                         |
| `sign_type`   | string  | O           | Signature algorithm used for the request or notification.                                                                                                                                                 |
| `request_id`  | string  | M           | Globally unique identifier used to trace the notification and support idempotent processing.                                                                                                              |
| `notify_type` | integer | M           | <p>Numeric code identifying the notification event type.<br>See <a href="https://docs.pagsmile.com/reference/remittance-api/data/dictionary-item/webhook-type">Webhook Type</a> for supported values.</p> |
| `biz_data`    | obj     | M           | Business payload whose schema depends on the notification type.                                                                                                                                           |

**Notification envelope example**

```json
{
  "partner_id": "200000001000001",
  "timestamp": "2026-07-20 10:30:00",
  "version": "2.0",
  "random_key": "",
  "sign_type": "",
  "request_id": "6f5b2e6c-44f0-4f38-9848-fbf7ca7d1c47",
  "notify_type": 100,
  "biz_data": {
  }
}
```

**Acknowledgment**

Return any HTTP `2xx` status to acknowledge successful receipt. Any other status is treated as a delivery failure.

{% hint style="warning" %}
Failed deliveries are retried up to 7 times after approximately 10 seconds, 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, and 24 hours. Process notifications idempotently because the same event may be delivered more than once.
{% endhint %}

**Related APIs**

* [Create Webhook URL](https://docs.pagsmile.com/remittance-api/business/webhook/manage-url/create-webhook-url)
* [Manage URL](https://docs.pagsmile.com/remittance-api/business/webhook/manage-url)
* [Query Webhook URL](https://docs.pagsmile.com/remittance-api/business/webhook/manage-url/query-webhook-url)
* [Update Webhook URL](https://docs.pagsmile.com/remittance-api/business/webhook/manage-url/update-webhook-url)