> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payglocal.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Real-time event notifications for your application.

## Overview

Webhook notifications are sent to the webhook URL shared by the merchant. There are no additional integration steps required to implement and receive responses on webhook.

To receive webhook responses, share a webhook URL with PayGlocal on which you want to be notified about the status of your transactions.

**Example webhook URL:**

```
https://www.nameofyourwebsite.com/payment/payglocal/webhook_response
```

Once the webhook URL is configured on your MID based on your request, you will start receiving the response for all transactions as per the configuration.

<Note>
  To get your webhook URL configured, contact your PayGlocal account manager or write to [merchant.support@payglocal.in](mailto:merchant.support@payglocal.in).
</Note>

***

## How to Form Your Webhook URL

Your webhook URL is simply a **publicly accessible POST endpoint** on your own backend server. You build it yourself — PayGlocal will call it whenever a payment event occurs.

A typical webhook URL follows this pattern:

```
https://<your-domain>/<your-path>/webhook
```

**Examples:**

```
https://api.yourstore.com/payments/payglocal/webhook
https://backend.yourapp.in/payglocal/notify
https://yourwebsite.com/payment/payglocal/webhook_response
```

**Rules for a valid webhook URL:**

* Must be **HTTPS** (HTTP is not accepted)
* Must be **publicly reachable** — localhost or private IPs will not work
* Must accept **HTTP POST** requests
* Must return **HTTP 200** to acknowledge receipt

***

## Setting Up Your Webhook Endpoint

You need to create a POST endpoint on your backend that PayGlocal can call. The endpoint receives a JSON body and must respond with `200 OK`.

Here is what your endpoint needs to do:

```
1. Listen for POST requests at your webhook URL
2. Read the JSON body from the incoming request
3. Return HTTP 200 immediately
4. Process the event (update order, notify user, etc.) after responding
```

**Pseudo-code for any backend (Node, Python, Java, etc.):**

```
POST /payglocal/webhook

  → Read request body (JSON)
  → Validate that merchantId matches your own MID
  → Respond with HTTP 200 OK immediately
  → Trigger your business logic (mark order paid, send receipt, etc.)
```

<Warning>
  Always return **HTTP 200** before running any business logic. If your server takes too long to respond, PayGlocal may consider the delivery failed and retry the webhook.
</Warning>

***

## Real-Time Event Notifications

Webhooks enable your application to receive instant notifications when events occur in PayGlocal, eliminating the need for constant polling and enabling real-time, event-driven workflows.

<CardGroup cols={3}>
  <Card title="What is a Webhook?" icon="webhook" color="#1A6FE8">
    An automated HTTP POST request sent from PayGlocal to your server the moment a payment event occurs — no polling needed.
  </Card>

  <Card title="Why Use Webhooks?" icon="bolt" color="#10B981">
    Instant notifications, no polling overhead, reduced server load, and event-driven workflows for faster applications.
  </Card>

  <Card title="When to Use" icon="clock" color="#F59E0B">
    Payment status updates, order confirmations, transaction monitoring, and any scenario requiring immediate event-based action.
  </Card>
</CardGroup>

***

## Webhook Flow

```
1. Event Occurs
   Payment is processed on PayGlocal
         │
         ▼
2. Webhook Triggered
   PayGlocal sends a POST request to your webhook URL
         │
         ▼
3. Your Server Receives
   Your endpoint receives the webhook payload
         │
         ▼
4. Process & Respond
   Handle the event and return HTTP 200
         │
         ▼
5. Action Taken
   Update your database, fulfil the order, notify the user
```

***

## Sample Webhook Payload

When an event occurs, PayGlocal sends a POST request to your configured webhook URL. Here is an example of the payload your server receives:

```json theme={null}
{
  "country": "UNITED KINGDOM",
  "amount": "48",
  "gid": "gl_o-pYA8MLrsnfVpKp1mw",
  "merchantId": "alwyntest1",
  "merchantTxnId": "17083906765",
  "paymentMethod": "CARD",
  "currency": "USD",
  "cardBrand": "VISA",
  "status": "SENT_FOR_CAPTURE"
}
```

### Payload Field Reference

| Field           | Description                                   |
| --------------- | --------------------------------------------- |
| `country`       | Country of the card used for payment          |
| `amount`        | Transaction amount                            |
| `gid`           | PayGlocal's unique transaction identifier     |
| `merchantId`    | Your Merchant ID                              |
| `merchantTxnId` | Your unique transaction reference             |
| `paymentMethod` | Payment method used (e.g. `CARD`)             |
| `currency`      | Currency of the transaction                   |
| `cardBrand`     | Card network used (e.g. `VISA`, `MASTERCARD`) |
| `status`        | Final transaction status                      |

***

## Payment Status Values

| Status               | Meaning                                  |
| -------------------- | ---------------------------------------- |
| `SENT_FOR_CAPTURE`   | Payment successful — funds captured      |
| `AUTHORIZED`         | Payment authorized, awaiting capture     |
| `ISSUER_DECLINE`     | Card declined by the issuing bank        |
| `CUSTOMER_CANCELLED` | Customer cancelled the payment           |
| `ABANDONED`          | Customer left without completing payment |
| `GENERAL_DECLINE`    | Declined due to risk or fraud check      |

***