# Webhook Connection

### **1. Webhook Request Overview**

When a transaction or event occurs, our system will send a POST request to the user's webhook URL. The request contains the following:

#### **Headers**

| Header         | Description                                                                                       |
| -------------- | ------------------------------------------------------------------------------------------------- |
| `X-Signature`  | HMAC ( Hash-based Message Authentication Code ) signature for validating the payload's integrity. |
| `Content-Type` | Always `application/json`.                                                                        |
| `Accept`       | Always `application/json`.                                                                        |

#### **Body**

The body of the request contains an encrypted payload in the `data` field:

```json
{
    "data": "<encrypted_payload>"
}
```

***

### **2. Encryption and Signature Details**

#### **Encryption**

* **Algorithm**: AES-256-CBC
* **IV (Initialization Vector)**: Randomly generated and prefixed to the encrypted payload.
* **Key**: Webhook Secret Key entered while creating Webhook URL.

#### **Signature**

* **Algorithm**: HMAC-SHA256
* **Payload for Signature**: A hashed version of the secret key (`hash('sha256', $secretKey)`).

### **User Implementation**

To receive, validate, and decrypt the webhook data, follow the steps below:

#### **Step 1: Validate the Signature**

1. Extract the `X-Signature` header from the request.
2. Recalculate the signature using the provided secret key:
   * Generate the signature payload: `hash('sha256', $secretKey)`.
   * Generate the expected signature: `hash_hmac('sha256', $signature_payload, $secretKey)`.
3. Compare the recalculated signature with the received `X-Signature` using a secure comparison method (e.g., `hash_equals`).

#### **Step 2: Decrypt the Payload**

1. Extract the `data` field from the request body.
2. Decode the payload from `Base64`.
3. Split the decoded data into:
   * **IV**: The first 16 bytes.
   * **Encrypted Data**: The remaining bytes.
4. Decrypt the encrypted data using `AES-256-CBC` with the secret key and IV.

#### **Step 3: Process the Decrypted Data**

Once decrypted, the payload is a JSON object. Parse the JSON and use it according to your business logic.

### **Debugging Tips**

1. **Signature Validation Fails**:
   * Ensure the secret key matches the one used by our system.
   * Confirm that the hashing algorithms (`sha256`) are consistent.
2. **Decryption Errors**:
   * Verify that the IV extraction logic is correct (first 16 bytes of the decoded data).
   * Ensure the secret key and encryption algorithm (`AES-256-CBC`) are consistent.
3. **Payload Parsing Fails**:
   * Ensure the decrypted data is valid JSON.

### **Encrypted Payload Details**

When a webhook call is made to the user's system, the `data` field in the request body contains an encrypted payload. This payload includes transaction details related to the event. Users must decrypt this payload to access the information.

#### **1. Encrypted Payload Structure**

The encrypted payload contains the following fields:

| **Field**               | **Description**                                                      |
| ----------------------- | -------------------------------------------------------------------- |
| `status`                | The transaction status (e.g., `success`, `failed`, `pending`).       |
| `transaction_id`        | Unique identifier for the transaction.                               |
| `order_id`              | Order ID associated with the transaction.                            |
| `amount`                | The transaction amount.                                              |
| `timestamp`             | The timestamp when the transaction occurred.                         |
| `details.connection_no` | The connection number or user identifier related to the transaction. |
| `details.operator`      | The operator or service related to the transaction.                  |
| `package_name`          | The package name, if applicable, for the service or product.         |

***

#### **2. Example Payload**

Before encryption, the payload is structured as follows:

```json
{
    "status": "success",
    "transaction_id": "123456789",
    "order_id": "987654321",
    "amount": 500.75,
    "timestamp": "2024-12-31T12:34:56Z",
    "details": {
        "connection_no": "098764321",
        "operator": "XYZ Telecom"
    },
    "package_name": "Premium Plan"
}
```

***

###


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.globaltopup.in/developer-tools/webhook-connection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.