Webhook
Security & Signature
When Baokim calls the merchant's webhook, Baokim also signs the request body using SHA256withRSA and sends the signature in the Signature header. The merchant should verify this signature using Baokim's public key before processing the data, similar to how Baokim verifies requests from the merchant.
Success Condition
Baokim considers webhook delivery successful when receiving a response from the merchant with:
- HTTP status code: 200
- Response time within the allowed timeout limit
Merchant must return body confirming receipt. The code value differs by API group:
| API Group | Confirmation Body | Note |
|---|---|---|
| VA (Direct), Master Merchant Basic/Pro | { "code": 0, "message": "Success" } | code = 0 — confirmed in the original documentation |
| BNPL, Installment, International Card (Direct & Master), Master VA, Master Credit Card | { "code": 0, "message": "Success" } | ⚠️ The original documentation does not specify the ACK value — tentatively inferred from the VA group, requires developer confirmation before use in production |
| QRPay/QRGlobal | { "code": 100, "message": "Success" } | code = 100 — confirmed in the original documentation |
⚠️ Note: If QRPay/QRGlobal webhook returns
code = 0, Baokim will not record success and will continue retrying.
⚠️ Deeplink does not yet have a documented Webhook mechanism. The original documentation only states that "Baokim notifies the Partner of the result" without specifying a URL, method, headers, or field structure, and does not state an ACK code value. Do not apply the B2B group's
code = 0convention until developers confirm and supplement the documentation.
Retry & Timeout
If webhook delivery fails (timeout or HTTP status != 200), Baokim will retry using a backoff mechanism. The merchant must ensure the webhook endpoint:
- Can process and respond quickly (avoid heavy synchronous processing in webhook handler).
- Can handle receiving duplicate webhooks (idempotent) — use
request_idfor deduplication.
Retry mechanism by API group:
| API Group | Retry Mechanism | Max Attempts | Timeout |
|---|---|---|---|
| VA (Direct), Master Merchant Basic/Pro | Backoff | 10 times | 30 seconds |
| QRPay/QRGlobal | Fibonacci: 1 - 2 - 3 - 5 - 8 minutes | 5 times | 30 seconds |
⚠️ The retry mechanism for BNPL, Installment, International Card, Master VA, Master Credit Card, and Deeplink has not been confirmed in the original documentation — the table above only applies tentatively to VA/Master Basic-Pro (backoff, 10 times) and QRPay (Fibonacci); requires developer confirmation before use in production for the remaining groups.
Common Headers
Each webhook request from Baokim to merchant includes the following headers:
| Header | Description |
|---|---|
| Content-Type | application/json |
| Signature | SHA256withRSA signature from Baokim on request body |
The webhook body typically contains these fields for event identification:
| Field | Description |
|---|---|
| request_id | Unique ID of webhook request |
| request_time | Time Baokim sent webhook |
merchant_code / master_merchant_code | Merchant identifier |
| operation | Event type: PAYMENT, REFUND, AUTHENTICATION, etc. |