VTPE Webhook Events and Delivery

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:

{
  "event": "string",
  "data": {}
}

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

payment.initialized
payment.success
payment.fail

Sent when a payment session is created:

{
  "event": "payment.initialized",
  "data": {
    "reference": "ORDER-1001",
    "amount": 2500,
    "currency": "DZD",
    "paymentId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Sent when the customer completes the payment:

{
  "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"
  }
}

Sent when the payment fails or is cancelled:

{
  "event": "payment.fail",
  "data": {
    "reference": "ORDER-1001",
    "paymentId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Acknowledging Webhooks

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

{
  "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.

Always verify the X-Signature header before processing any webhook payload. Unverified webhooks may be forged.

Get Started

Core Concepts

Guides

Reference

VTPE Webhook Events and Delivery

Webhook Request Headers

Event Envelope

Acknowledging Webhooks

Retry Behavior

Signature Verification

​Webhook Request Headers

​Event Envelope

​Acknowledging Webhooks

​Retry Behavior

​Signature Verification

Webhook Request Headers

Event Envelope

Acknowledging Webhooks

Retry Behavior

Signature Verification