# Webhook

## 1. Overview

Keeta actively pushes various notifications to service provider applications via webhook, including:

- Order
- Store Status
- Menu Synchronization Result


## 2. Configuring Webhook URL

Please choose **one** of the following methods:

### 2.1 Method 1: Official Website Configuration

1. Log in to your developer account on Keeta's official website
2. Navigate to Application Management
3. Configure your webhook URL in the designated section


### 2.2 Method 2: API Configuration

Configure via Keeta API:


```JSON
// Demo
curl -X POST 'https://open.mykeeta.com/api/open/base/callback/url/set' \
-H 'Content-Type: application/json' \
--data-raw '{
    "appId": 2061048026,
    "timestamp": "1723001797",
    "sig": "e12ae63e917752bca3fd5d0eceec42337f2338f4d9303ac30e3eb4856900b07c",
    "eventId": 1001,
    "url": "https://<vendor'\''s url>",
    "isTest": 1
}'
```

## 3. Webhook Message Definition

| **Field Key** | **Type** | **Description** |
|  --- | --- | --- |
| sig | String | A string calculated according to specific rules (see [Authorization Guide](/apis/standard/docs/author) for details). Developers must use this signature to verify whether the request originates from Keeta, thereby guaranteeing message security and accuracy. |
| eventId | Integer | **Code representing the message type**. Please refer to the event code enumeration later in this document. |
| appId | long | **Application ID**, unique identifier assigned by the system when the application is created. |
| messageId | String | **Unique identifier** for the message. |
| shopId | Long | **Keeta store ID** |
| message | String | **Message content** regarding orders, stores, or products. For specific definitions, refer to the API reference chapter. |
| timestamp | Long | **Message push timestamp** in seconds (Unix epoch time). |


Message example:


```JSON
// Demo
{
  "sig": "6d2581a5e71cdddc6f8770d0e84b2aa02ec72158190b39d97df2e5d5c314b7a0",
  "eventId": 1002,
  "appId": 3762772727,
  "messageId": "1930106161957212198",
  "shopId": 145541,
  "message": "{\"opTime\":1749008143025,\"orderViewId\":553440887574627,\"shopId\":145541,\"status\":30}",
  "timestamp": 1749008143
}
```

## 4. Webhook Request Protocol

1. Webhook requests use the HTTPS protocol, employ the POST method, have a Content-Type of "application/json", and use UTF-8 encoding.
2. Webhooks must support Keeta's heartbeat detection. During heartbeat detection, Keeta sends an empty packet. Developers must handle empty packet requests and return a success response.
3. After processing, the response should be in JSON format. The specific format can be found in the following description:



```JSON
// Webhook repsonse
{
  "code": 0,
  "message": "success"
  "data": {}
}
```

| **Field Key** | **Type** | **Requirement** | **Description** |
|  --- | --- | --- | --- |
| code | Integer | **Mandatory** | **A code value of 0 indicates successful acceptance**. **Any non-zero code value indicates processing failure**. |
| message | String | Optional | Supplementary explanation of the code value. |
| data | Object | Optional | Additional error details for failure scenarios. |


1. Pushed messages contain signatures. **Developers must verify message signatures.**
2. **All APIs provided by developers must support idempotency.** In the event of a request failure or network timeout, the Keeta platform will automatically retry, typically up to 3 times with 1-minute intervals, to ensure that multiple identical requests have the same effect as a single request.
3. **How to determine if a message is a retry:** Developers can filter based on order data. For example, when Keeta retries a paid order notification, developers should check whether the order ID has already been processed. If the message has been processed, it should be ignored.


## 5. Enumeration of Event ID (Extract)

**For configuration details, refer to the 'Edit Application' in Developer Portal.**

|  | **eventId** | **Event Description** |
|  --- | --- | --- |
|  | 1001 | Order Placement Notification |
|  | 1002 | Order Acceptance Notification |
|  | 1003 | Order Completion Notification |
|  | 1004 | Order Cancellation Notification |
|  | 1005 | Refund Initiation Notification |
|  | 1006 | Delivery Status Update Notification |
|  | 1007 | Partial Refund Initiation Notification |
|  | 1101 | Store Business Hours Change Notification |
|  | 1102 | Store Status Change Notification |
|  | 1201 | Batch Product Image Binding Result Notification |