# Validate the Webhooks

### Connect Webhook

You can connect to the webhooks to verify payloads or check if your webhook integration is working. This section provides guidelines for vendors on how to configure and verify the connection of their webhook URL to our system. When the "Not Connected" button is clicked on the **Webhook Settings** page, our system performs a `GET` request to the vendor’s webhook URL to verify its availability and functionality. If the webhook responds with a successful status, it is marked as connected.

### **How the Webhook Connection Works**

1. **Connection Verification Request**:
   * When the "Connect" button is clicked, our system sends a `GET` request to the webhook URL configured by the vendor.
2. **Request Headers**:
   * The request includes an `X-Signature` header for verification.
   * The `X-Signature` is generated using the vendor's secret key to ensure security.
3. **Expected Response**:
   * The webhook URL should respond with:
     * **Status Code**: `200 OK`
     * **Content-Type Header**: `application/json`
4. **Successful Connection**:
   * If the response meets the above conditions, the webhook is marked as connected and active.

### **Webhook Verification Request Details**

#### **Headers**

| Header         | Description                                         |
| -------------- | --------------------------------------------------- |
| `X-Signature`  | HMAC signature for verifying the request integrity. |
| `Content-Type` | Always `application/json`.                          |
| `Accept`       | Always `application/json`.                          |

#### **Example GET Request**

```http
GET /some-webhook-endpoint HTTP/1.1
Host: url_added_by_you.xyz
X-Signature: <calculated_signature>
Content-Type: application/json
Accept: application/json
```

***

### **Expected Response from the Vendor**

The webhook URL should respond with:

* **Status Code**: `200 OK`
* **Content-Type Header**: `application/json`
* **Body (optional)**: A JSON response confirming that the webhook is active.

#### **Example Response**

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "message": "Webhook is active and reachable"
}
```

### **How You Should Handle the Request**

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

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

***Note:*** You will have to use the same secret key that you have added while creating the webhook on the Globaltopup dashboard.

#### **Step 2: Respond with a Success Message**

If the signature matches, respond with a `200 OK` status and a JSON message.

#### Note: Application Running on Localhost <a href="#application-running-on-localhost" id="application-running-on-localhost"></a>

You cannot use localhost directly to receive webhook events as webhook delivery requires a public URL. You can handle this by creating a tunnel to your localhost using tools such as [ngrok](https://ngrok.com/) or [localtunnel](https://localtunnel.github.io/www/).

You can refer to the [ngrok documentation](https://ngrok.com/docs#getting-started-expose) to get started. Use the URL endpoint generated by these tools in the webhook URL while setting up your webhooks.

### **Troubleshooting**

1. **Invalid Signature**:
   * Ensure the secret key matches the one provided by you in our system.
   * Verify that the hashing algorithms (`sha256`) are consistent.
2. **Endpoint Not Reachable**:
   * Ensure the webhook URL is publicly accessible.
   * Check for network or firewall issues that might block our request.
3. **Unexpected Status Code**:
   * Ensure your endpoint returns a `200 OK` status code upon successful validation.


---

# 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/validate-the-webhooks.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.