> ## Documentation Index
> Fetch the complete documentation index at: https://beta-developers.mizaniyapay.dz/llms.txt
> Use this file to discover all available pages before exploring further.

# VTPE Webhook Events and Delivery

> VTPE sends signed POST webhooks for payment events. Learn about the event envelope, the three event types, retry behavior, acknowledgement, and signature verification.

VTPE delivers real-time payment lifecycle events to your Webhook URL via signed POST requests. This page describes the request headers, event envelope structure, the three event types, how to acknowledge delivery, retry behavior, and how to verify webhook signatures.

## Webhook Request Headers

Every webhook request from VTPE includes the following three headers:

| Header          | Description                                                                   |
| --------------- | ----------------------------------------------------------------------------- |
| `Authorization` | Bearer token containing your API Secret, identical to other VTPE requests     |
| `X-Timestamp`   | Unix timestamp used in signature generation, also for basic replay protection |
| `X-Signature`   | HMAC-SHA256 signature proving the request originated from VTPE                |

## Event Envelope

All VTPE webhook events use a common envelope:

```json theme={null}
{
  "event": "string",
  "data": {}
}
```

The `event` field identifies the payment lifecycle stage. The `data` field contains event-specific payload data.

<Tabs>
  <Tab title="payment.initialized">
    Sent when a payment session is created:

    ```json theme={null}
    {
      "event": "payment.initialized",
      "data": {
        "reference": "ORDER-1001",
        "amount": 2500,
        "currency": "DZD",
        "paymentId": "123e4567-e89b-12d3-a456-426614174000"
      }
    }
    ```
  </Tab>

  <Tab title="payment.success">
    Sent when the customer completes the payment:

    ```json theme={null}
    {
      "event": "payment.success",
      "data": {
        "reference": "ORDER-1001",
        "amount": 2500,
        "currency": "DZD",
        "paidAt": "2026-06-02T15:30:00Z",
        "paymentId": "123e4567-e89b-12d3-a456-426614174000",
        "channel": "AGENCY"
      }
    }
    ```
  </Tab>

  <Tab title="payment.fail">
    Sent when the payment fails or is cancelled:

    ```json theme={null}
    {
      "event": "payment.fail",
      "data": {
        "reference": "ORDER-1001",
        "paymentId": "123e4567-e89b-12d3-a456-426614174000"
      }
    }
    ```
  </Tab>
</Tabs>

## Acknowledging Webhooks

Your endpoint must return HTTP 200 with the following JSON body to confirm receipt:

```json theme={null}
{
  "success": true
}
```

If your endpoint returns a non-2xx status code, VTPE will not consider the delivery successful and may retry the request.

## Retry Behavior

VTPE retries webhook deliveries when your endpoint returns a non-2xx response. To handle retries safely, make your webhook handler idempotent. Use the `paymentId` field as a unique key to deduplicate events and prevent duplicate side effects in your system.

## Signature Verification

Always verify the `X-Signature` header before processing any webhook payload. VTPE signs each webhook using HMAC-SHA256 of the raw request body concatenated with the `X-Timestamp` value. For complete implementation details, see the [Webhook Security guide](/guides/webhook-security).

<Warning>
  Always verify the `X-Signature` header before processing any webhook payload. Unverified webhooks may be forged.
</Warning>