> For the complete documentation index, see [llms.txt](https://docs.paymento.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.paymento.io/payment-links/webhooks-for-payment-links/integration-reference.md).

# Integration Reference

#### HTTP Headers

Every webhook request includes the following headers for authentication and tracking:

{% code expandable="true" %}

```http
POST /your-webhook-endpoint HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Paymento-Signature: 9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b
X-Paymento-Timestamp: 1699564800
X-Paymento-Event-Id: evt_a1b2c3d4e5f6g7h8i9j0
X-Paymento-Event-Type: payment_link.paid
```

{% endcode %}

#### **Header Descriptions**

| Header Name             | Type      | Description                                            |
| ----------------------- | --------- | ------------------------------------------------------ |
| `X-Paymento-Signature`  | `string`  | HMAC-SHA256 signature of the request body (hex string) |
| `X-Paymento-Timestamp`  | `integer` | Unix timestamp when the webhook was sent               |
| `X-Paymento-Event-Id`   | `string`  | Unique identifier for this webhook event               |
| `X-Paymento-Event-Type` | `string`  | Type of event (see Event Types section)                |

#### Request Body

The webhook request body is a JSON object with the following structure:

{% code expandable="true" %}

```json
{
  "event": {
    "id": "evt_a1b2c3d4e5f6g7h8i9j0",
    "type": "payment_link.paid",
    "createdAt": "2024-11-09T14:30:00Z",
    "apiVersion": "v1"
  },
  "paymentLink": {
    "id": "pl_9z8y7x6w5v4u3t2s1r0q",
    "title": "Monthly Subscription",
    "description": "Premium Plan - November 2024",
    "status": "paid",
    "type": "scheduled",
    "createdAt": "2024-10-01T10:00:00Z",
    "paidAt": "2024-11-09T14:30:00Z",
    "url": "https://app.paymento.com/pl_9z8y7x6w5v4u3t2s1r0q"
  },
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe",
    "metadata": {
      "order_id": "12345",
      "payment_id": "pay_abcdefghijk"
    }
  },
  "merchant": {
    "id": "mrc_xyz123",
    "name": "Your Store Name"
  }
}
```

{% endcode %}

#### **Object Descriptions**

**`event` Object**

| Field        | Type     | Description                                        |
| ------------ | -------- | -------------------------------------------------- |
| `id`         | `string` | Unique identifier for this event (format: `evt_*`) |
| `type`       | `string` | Event type (see Event Types)                       |
| `createdAt`  | `string` | ISO 8601 timestamp when the event was created      |
| `apiVersion` | `string` | Paymento API version used                          |

**`paymentLink` Object**

| Field                 | Type      | Description                                                                      |
| --------------------- | --------- | -------------------------------------------------------------------------------- |
| `id`                  | `string`  | Unique payment link identifier                                                   |
| `title`               | `string`  | Payment link title                                                               |
| `description`         | `string`  | Payment link description                                                         |
| `status`              | `string`  | Current status: `"paid"`, `"deferred"`, or `"scheduled"`                         |
| `type`                | `string`  | Payment type: `"one_time"` or `"scheduled"`                                      |
| `createdAt`           | `string`  | ISO 8601 timestamp when payment link was created                                 |
| `paidAt`              | `string?` | ISO 8601 timestamp when payment was completed (null if not paid)                 |
| `url`                 | `string`  | Public URL of the payment link                                                   |
| `integrationMetadata` | `object`  | Integration metadata for external platforms (Telegram, Discord, etc.) - optional |

**`customer` Object**

| Field                        | Type      | Description                                                  |
| ---------------------------- | --------- | ------------------------------------------------------------ |
| `email`                      | `string`  | Customer email address                                       |
| `name`                       | `string`  | Customer name                                                |
| `metadata`                   | `object`  | Additional customer metadata (optional)                      |
| `metadata.order_id`          | `string?` | Order ID if available                                        |
| `metadata.payment_id`        | `string?` | Payment transaction ID if available                          |
| `metadata.scheduled_token`   | `string?` | Scheduled payment token (for reminder/deferred events)       |
| `metadata.payment_link_url`  | `string?` | Payment link URL (for reminder events)                       |
| `metadata.due_date`          | `string?` | Due date in YYYY-MM-DD format (for scheduled payments)       |
| `metadata.grace_date`        | `string?` | Grace period end date in YYYY-MM-DD format (if applicable)   |
| `metadata.telegram_username` | `string?` | Customer's Telegram username (if available)                  |
| `metadata.telegram_user_id`  | `string?` | Customer's Telegram user ID (only for Telegram integrations) |

**`merchant` Object**

| Field  | Type     | Description            |
| ------ | -------- | ---------------------- |
| `id`   | `string` | Your merchant/store ID |
| `name` | `string` | Your store name        |