# Webhook Event

The **Payment Processing Completed Webhook** is sent by Convergegate to notify your system when a payment has reached a **finalized state**.\
This webhook enables real-time updates in your application without polling the API.

***

#### 🔒 Authorization

* **Type:** `SignatureAuth`
* **Signature Algorithm:** `HMAC-SHA256`
* **Secret:** Shop Signing Key
* **Header Parameter Name:** `Signature`
* The signature is computed from the **raw JSON request body** using the Shop Signing Key as the HMAC secret.

> **⚠️ Important:**\
> The `Signature` header is only included **after** a **Signing Key** has been generated for the shop.\
> Without a Signing Key, webhook requests will **not** include this header.\
> You can generate a Signing Key in the merchant back office.

***

#### Webhook URL

The webhook endpoint must be implemented by the merchant and exposed via HTTPS.\
Your server should respond with **HTTP 200 OK** to confirm successful receipt. Any non-2xx response will trigger retries according to Convergegate retry policy.

***

#### Payload Structure

**Content-Type:** `application/json`

| Field                        | Type                 | Description                                                            |
| ---------------------------- | -------------------- | ---------------------------------------------------------------------- |
| `id`                         | string (≤ 32 chars)  | Payment ID.                                                            |
| `referenceId`                | string (≤ 256 chars) | Merchant-provided reference ID.                                        |
| `created`                    | string (ISO 8601)    | Payment creation date/time (UTC).                                      |
| `paymentType`                | string               | One of: `DEPOSIT`, `WITHDRAWAL`, `REFUND`.                             |
| `state`                      | string               | Final state: `COMPLETED`, `DECLINED`, `CANCELLED`.                     |
| `description`                | string (≤ 512 chars) | Transaction description.                                               |
| `parentPaymentId`            | string (≤ 32 chars)  | ID of the initial payment in the chain.                                |
| `paymentMethod`              | string               | One of: `BASIC_CARD`, `BASIC_CARD_HPP`, `PIX`, `OPEN_BANKING`, `BLIK`. |
| `paymentMethodDetails`       | object               | Amount, currency, and provider-specific info.                          |
| `errorCode` / `errorMessage` | string               | Populated for failed payments.                                         |
| `customer`                   | object               | Customer and billing details.                                          |
| `redirectUrl`                | string               | Redirect URL for the customer (if applicable).                         |

**Example Webhook Body**

```json
{
  "id": "a1b2c3d4e5f6g7h8i9j0",
  "referenceId": "ORDER-12345",
  "created": "2025-08-14T15:32:00Z",
  "paymentType": "DEPOSIT",
  "state": "COMPLETED",
  "description": "Payment for ORDER-12345",
  "parentPaymentId": "z9y8x7w6v5u4t3s2r1q0",
  "paymentMethod": "BLIK",
  "paymentMethodDetails": {
    "amount": 100.00,
    "currency": "PLN"
  },
  "customer": {
    "billingAddress": {
      "line1": "Main Street 123",
      "city": "Warsaw",
      "country": "PL",
      "zip": "00-410"
    }
  }
}
```

#### Verifying the Signature

1. Retrieve the `Signature` header from the webhook request.
2. Compute `HMAC-SHA256` over the **raw JSON body** using the **Shop Signing Key**.
3. Compare the result to the value in the `Signature` header.
4. Reject the request if the values do not match.

***

#### Best Practices

* Always validate the signature before processing the webhook.
* Store and log the raw webhook payload for troubleshooting.
* Use **idempotency** in your processing logic to avoid double updates.
* Make sure your webhook endpoint is **publicly accessible** and **HTTPS-secured**.


---

# 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://developer.convergegate.com/v1/overview/webhook-event.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.