Agreement Webhooks

Agreement webhooks notify merchants about agreement lifecycle changes. All agreement webhooks use notifyType: AGREEMENT_STATUS.

---

Sign Result Notification

Notifies merchant when user completes or fails the sign process.

data Fields

Parameter	Type	Description
agreementNo	string	Platform agreement number
externalAgreementNo	string	Merchant agreement number
agreementType	string	Sign type: CYCLE / NON_CYCLE / SINGLE
eventType	string	Event type: SIGNED / FAILED
status	string	Sign status: SIGNED / FAILED
userId	string	Platform user ID
merchantUserId	string	Merchant-side user ID
sceneCode	string	Scene code
signTime	string	Sign time (on success)
failureCode	string	Failure error code (on failure, 9-digit string)
failureReason	string	Failure reason description (on failure)

Example (Success)

{
  "notifyId": "NOTIFY202601070001",
  "notifyType": "AGREEMENT_STATUS",
  "notifyTime": "2026-01-07T10:30:05+08:00",
  "merchantId": "M123456789",
  "data": {
    "agreementNo": "AGR202601070001",
    "externalAgreementNo": "MERCHANT_AGR_001",
    "agreementType": "CYCLE",
    "eventType": "SIGNED",
    "status": "SIGNED",
    "userId": "U_123456789",
    "merchantUserId": "merchant_user_123",
    "sceneCode": "SUBSCRIPTION",
    "signTime": "2026-01-07 10:30:00"
  },
}

Example (Failure)

{
  "notifyId": "NOTIFY202601070002",
  "notifyType": "AGREEMENT_STATUS",
  "notifyTime": "2026-01-07T10:35:05+08:00",
  "merchantId": "M123456789",
  "data": {
    "agreementNo": "AGR202601070002",
    "externalAgreementNo": "MERCHANT_AGR_002",
    "agreementType": "CYCLE",
    "eventType": "FAILED",
    "status": "FAILED",
    "userId": "U_123456789",
    "merchantUserId": "merchant_user_123",
    "sceneCode": "SUBSCRIPTION",
    "failureCode": "139001001",
    "failureReason": "User authentication timeout (downstream code=300100002, msg=User auth timeout)"
  },
}

---

Unsign Notification

Notifies merchant when an agreement is terminated.

data Fields

Parameter	Type	Description
agreementNo	string	Platform agreement number
externalAgreementNo	string	Merchant agreement number
eventType	string	Event type: UNSIGNED
status	string	Agreement status: UNSIGNED
unsignType	string	Unsign type: USER / MERCHANT / EXPIRED / SYSTEM
unsignTime	string	Unsign time

Example

{
  "notifyId": "NOTIFY202601070006",
  "notifyType": "AGREEMENT_STATUS",
  "notifyTime": "2026-01-07T15:30:05+08:00",
  "merchantId": "M123456789",
  "data": {
    "agreementNo": "AGR202601070001",
    "externalAgreementNo": "MERCHANT_AGR_001",
    "eventType": "UNSIGNED",
    "status": "UNSIGNED",
    "unsignType": "USER",
    "unsignTime": "2026-01-07 15:30:00"
  },
}

---

Suspend Notification

Notifies merchant when an agreement is suspended due to risk control or abnormality.

data Fields

Parameter	Type	Description
agreementNo	string	Platform agreement number
externalAgreementNo	string	Merchant agreement number
eventType	string	Event type: SUSPENDED
status	string	Agreement status: SUSPENDED
suspendReason	string	Suspend reason: RISK / ABNORMAL / MANUAL
suspendTime	string	Suspend time

Example

{
  "notifyId": "NOTIFY202601070007",
  "notifyType": "AGREEMENT_STATUS",
  "notifyTime": "2026-01-07T16:30:05+08:00",
  "merchantId": "M123456789",
  "data": {
    "agreementNo": "AGR202601070001",
    "externalAgreementNo": "MERCHANT_AGR_001",
    "eventType": "SUSPENDED",
    "status": "SUSPENDED",
    "suspendReason": "RISK",
    "suspendTime": "2026-01-07 16:30:00"
  },
}

---

Resume Notification

Notifies merchant when a suspended agreement returns to normal.

data Fields

Parameter	Type	Description
agreementNo	string	Platform agreement number
externalAgreementNo	string	Merchant agreement number
eventType	string	Event type: SIGNED
status	string	Agreement status: SIGNED
resumeTime	string	Resume time

Example

{
  "notifyId": "NOTIFY202601070008",
  "notifyType": "AGREEMENT_STATUS",
  "notifyTime": "2026-01-07T18:30:05+08:00",
  "merchantId": "M123456789",
  "data": {
    "agreementNo": "AGR202601070001",
    "externalAgreementNo": "MERCHANT_AGR_001",
    "eventType": "SIGNED",
    "status": "SIGNED",
    "resumeTime": "2026-01-07 18:30:00"
  },
}

---

Sign Timeout Notification

Notifies merchant when sign link/QR code expires.

data Fields

Parameter	Type	Description
agreementNo	string	Platform agreement number
externalAgreementNo	string	Merchant agreement number
agreementType	string	Sign type: CYCLE / NON_CYCLE / SINGLE
eventType	string	Event type: TIMEOUT
status	string	Agreement status: TIMEOUT
userId	string	Platform user ID
merchantUserId	string	Merchant-side user ID
sceneCode	string	Scene code
timeoutTime	string	Timeout time

Example

{
  "notifyId": "NOTIFY202601070011",
  "notifyType": "AGREEMENT_STATUS",
  "notifyTime": "2026-01-07T11:00:05+08:00",
  "merchantId": "M123456789",
  "data": {
    "agreementNo": "AGR202601070003",
    "externalAgreementNo": "MERCHANT_AGR_003",
    "agreementType": "CYCLE",
    "eventType": "TIMEOUT",
    "status": "TIMEOUT",
    "userId": "U_123456789",
    "merchantUserId": "merchant_user_123",
    "sceneCode": "SUBSCRIPTION",
    "timeoutTime": "2026-01-07 11:00:00"
  },
}