---
name: webhooks
description: >-
  Guides through handling Smart Glocal API webhooks: setup, signature
  verification, IP allowlisting, async processing, retry logic, and all
  five webhook types (ready_to_confirm, action_required, ready_to_capture,
  payment_finished, payment_refunded).
---

# Webhooks

## Purpose

Use this skill to implement and secure Smart Glocal webhook handling — from endpoint setup and signature verification to processing each webhook type and handling retries.

## Primary references

- [Webhooks overview](https://developer.smart-glocal.com/reference/reference-webhooks)
- [ready_to_confirm](https://developer.smart-glocal.com/reference/webhooks/ready-to-confirm)
- [action_required](https://developer.smart-glocal.com/reference/webhooks/action-required)
- [ready_to_capture](https://developer.smart-glocal.com/reference/webhooks/ready-to-capture)
- [payment_finished](https://developer.smart-glocal.com/reference/webhooks/payment-finished)
- [payment_refunded](https://developer.smart-glocal.com/reference/webhooks/payment-refunded)

## Preconditions

- [ ] Public endpoint accessible from the internet (POST, JSON body)
- [ ] Smart Glocal public key downloaded:
  - **Live:** [smgl_public.pem](https://developer.smart-glocal.com/assets/smgl_public.pem)
  - **Demo:** [smgl_public_demo.pem](https://developer.smart-glocal.com/assets/smgl_public_demo.pem)
- [ ] Webhook URL provided to your Account Manager

---

Webhooks are HTTP notifications from Smart Glocal about events happening on the system side. They inform you of operation results, request confirmation, or alert you about required actions.

## How to Enable

1. Create an endpoint (URL) on your server that accepts POST requests with JSON bodies
2. Provide this URL to your Account Manager
3. Smart Glocal will start sending webhooks to this address

> If you prefer not to use webhooks, you can check operation statuses via the `session/status` method by polling.

## Security Best Practices

### 1. Verify Signature Before Parsing

Always verify the `X-PARTNER-SIGN` header **before** processing the webhook body. This prevents accepting spoofed payloads.

1. Get Smart Glocal's public key for your environment
2. Compute RSA SHA-256 signature of the raw request body
3. Compare with the `X-PARTNER-SIGN` header value (Base64-encoded)
4. If the signature does not match — discard the webhook immediately

### 2. IP Allowlisting

Smart Glocal sends webhooks from a fixed set of IP addresses. Contact your Account Manager for the current IP list and add them to your firewall allowlist.

If you cannot allowlist IPs, rely on signature verification alone — it is cryptographically secure.

### 3. Process Asynchronously

Respond with HTTP 200 **immediately** after receiving the webhook and verifying the signature. Process the business logic (update order status, send notifications) in a background job or queue. This ensures:

- Smart Glocal does not retry unnecessarily
- Your endpoint stays fast and reliable
- Temporary processing failures do not cause duplicate retries

## What to Respond

You **must respond with HTTP 200** to every webhook. If you don't:

- Smart Glocal will retry with increasing intervals (up to 15 minutes)
- After 30 minutes of failed attempts, sending stops

The response may contain additional fields depending on the payment method. Your system must handle such fields without errors.

## All Webhook Types

### ready_to_confirm

Smart Glocal is ready to perform the operation and is waiting for your decision.

**Action:** Check the parameters (amount, currency) and send `session/confirm` or `session/cancel`.

```
→ Received ready_to_confirm
→ Verify data
→ session/confirm (or session/cancel)
```

**Timeout:** 240 minutes. If no confirm/cancel is received within this time, the operation is automatically cancelled with status `canceled`.

```json
{
  "type": "ready_to_confirm",
  "session": {
    "id": "ps_xxx",
    "status": "in_progress",
    "next_action": "confirm",
    "payment_list": [{
      "id": "pm_xxx",
      "status": "pending",
      "payment_details": {
        "type": "card",
        "card": { "last4": "4242", "brand": "visa" }
      },
      "amount_details": {
        "amount": 10000,
        "currency": "usd"
      }
    }]
  }
}
```

---

### action_required

Additional action is needed — most commonly 3D Secure authentication for the buyer.

**Action:** Redirect the buyer to `customer_interaction.redirect.url`.

**Timeout:** 60 minutes.

```json
{
  "type": "action_required",
  "session": {
    "id": "ps_xxx",
    "status": "in_progress",
    "payment_list": [{
      "id": "pm_xxx",
      "status": "pending",
      "customer_interaction": {
        "type": "redirect",
        "redirect": {
          "url": "https://acs-bank.com/3ds?token=...",
          "method": "POST"
        }
      }
    }]
  }
}
```

> The redirect method can be `GET` or `POST` — handle both.

---

### ready_to_capture

Used in [delayed capture](https://developer.smart-glocal.com/assets/skills/delayed-capture/SKILL.md). The bank has successfully placed a hold on the funds. You can now capture or cancel.

**Action:** Send `session/capture` (debit) or `session/cancel` (release the hold).

```json
{
  "type": "ready_to_capture",
  "session": {
    "id": "ps_xxx",
    "status": "in_progress"
  }
}
```

---

### payment_finished

The operation has completed. Contains the final status.

**Action:** Check the `status` field and update the order status in your system.

```json
{
  "type": "payment_finished",
  "session": {
    "id": "ps_xxx",
    "status": "accepted",
    "payment_list": [{
      "id": "pm_xxx",
      "status": "succeeded",
      "amount_details": {
        "amount": 10000,
        "currency": "usd"
      },
      "transaction_info": {
        "rrn": "425307614918",
        "auth_code": "057441"
      }
    }]
  }
}
```

| Payment Status | Meaning |
|----------------|---------|
| `succeeded` | Operation successful |
| `failed` | Operation declined |
| `pending` | Still processing |

> **Important:** If the status is `failed` and the session status is `error`, do not retry immediately. The `error` status may be intermediate. Contact Smart Glocal support to confirm the final status.

---

### payment_refunded

The refund has completed. Funds have been returned to the buyer.

**Action:** Update the status in your system.

```json
{
  "type": "payment_refunded",
  "session": {
    "id": "ps_xxx",
    "payment_list": [{
      "id": "pm_xxx",
      "status": "succeeded",
      "refunds": [{
        "id": "rf_001",
        "status": "accepted",
        "amount_details": {
          "amount": 10000,
          "currency": "usd"
        }
      }]
    }]
  }
}
```

## Retry Logic

| Condition | Behavior |
|-----------|----------|
| Response 200 OK | Success, webhook delivered |
| Response 4xx/5xx | Retry with increasing interval (up to 15 min) |
| No response (timeout) | Retry with increasing interval (up to 15 min) |
| 30 minutes of failures | Sending stops |

## Important Links

- [Webhooks overview](https://developer.smart-glocal.com/reference/reference-webhooks)
- [ready_to_confirm](https://developer.smart-glocal.com/reference/webhooks/ready-to-confirm)
- [action_required](https://developer.smart-glocal.com/reference/webhooks/action-required)
- [ready_to_capture](https://developer.smart-glocal.com/reference/webhooks/ready-to-capture)
- [payment_finished](https://developer.smart-glocal.com/reference/webhooks/payment-finished)
- [payment_refunded](https://developer.smart-glocal.com/reference/webhooks/payment-refunded)