> ## 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: Complete Reference

> All three webhook events, common envelope, headers, acknowledgement format, and retry behavior for Mizaniya Pay VTPE integrations.

VTPE sends webhook events to notify your system about payment lifecycle changes. Your webhook handler receives all events at a single endpoint and must acknowledge each one with an HTTP 200 response. This page covers the common headers, envelope format, retry behavior, and the full event catalog.

## Webhook Request Headers

Every webhook request includes these headers.

| Header          | Value                    | Description                                            |
| --------------- | ------------------------ | ------------------------------------------------------ |
| `Authorization` | `Bearer YOUR_API_SECRET` | Used to authenticate the request origin.               |
| `X-Timestamp`   | Unix timestamp (seconds) | The time the event was generated.                      |
| `X-Signature`   | HMAC hex string          | HMAC-SHA256 signature for verifying request integrity. |

## Event Envelope

All webhook events share the same envelope structure:

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

The `event` field identifies the event type, and the `data` object contains event-specific fields.

## Retry Behavior

VTPE retries delivery when your endpoint returns any non-2xx status code. To avoid duplicate processing, you should:

* Return HTTP 200 as soon as you validate and queue the event.
* Implement idempotency checks using `paymentId` before performing any business action.
* Process events asynchronously when possible to minimize response latency.

## Acknowledging Events

Acknowledge every webhook event by returning HTTP 200 with this JSON body:

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

If VTPE does not receive a 200 response, it will retry delivery.

## Event Catalog

<CardGroup cols={2}>
  <Card title="payment.initialized" icon="bolt" href="/api-reference/webhooks/payment-initialized">
    Sent when a payment session is created for a reference.
  </Card>

  <Card title="payment.success" icon="check" href="/api-reference/webhooks/payment-success">
    Sent when a payment is successfully confirmed.
  </Card>

  <Card title="payment.fail" icon="xmark" href="/api-reference/webhooks/payment-fail">
    Sent when a payment fails or is cancelled.
  </Card>
</CardGroup>

<Warning>
  Always verify webhook signatures before trusting the payload. See the [Webhook Security guide](/concepts/webhook-security) for implementation details.
</Warning>