To receive notifications about various events undertaken by the user while they use the widget, you will need to set up an endpoint that accepts payloads sent by Wert. Your endpoint will receive POST requests with content-type application/json.

📘
While it’s not common, webhooks can fail, and we don’t recommend that any of our partners rely solely on them. You have access to on-chain data, and we have listeners and the data API; you should have redundancy in these situations.

❗️
We require your webhook server to return HTTP 2xx status on ALL received events. Any other HTTP status code like (4xx or 5xx) will be treated as NOT received and will automatically disable webhooks to your server. Please do not return any other HTTP status code that is related to your internal server side logic.
Webhook responses (2xx) must be sent within 5 seconds. To ensure stability, your endpoint should be asynchronous. Instead of processing data synchronously, your server should return a 2xx status first and handle the internal logic separately. Any delay beyond 5 seconds (Status Code 0) will be treated as a failure and lead to automatic disabling of your webhooks.
The system will make 5 retries of a failed webhook (non-2xx response) at intervals of 5m, 1h, 2h, 4h, and 8h. If all 5 retries fail, webhook delivery to your site will be disabled until manually re-enabled.
You may re-enable webhook sending at https://partner.wert.io or https://partner-sandbox.wert.io.

Configuring the webhook endpoint

The webhook endpoint can be set up on Partner Dashboard -> Webhooks -> Webhook URL. Make sure you save the endpoint by clicking “Save”.

From this page, you will also be able to see a log of all events that have been sent.

Wert module lifecycle

To get an overview of the entire module, the actions that can lead to certain events occurring, and further details for each transaction status, please see this graphic:

Events

The following events are available:

📘
Be sure to click on each event to see the respective return data.

Registration Event

📘
Triggered when a new user on your website creates a new Wert profile.

  {
    "type": "registration",
    "click_id": "click_id",
    "hpp_session_id": "b4e0c295-5379-480c-bdba-c2183992e44c",
    "user": {
      "user_id": "01K8W7CY66TG9YYJQ14EGTDSCQ",
      "verification_status": {
        "fkyc": {
          "state": "initiated"
        },
        "lkyc": {
          "state": "initiated"
        }
      }
    }
  }

📘
Triggered when an existing user logs into Wert on your website.

 {
   "type": "login",
   "click_id": "click_id",
   "hpp_session_id": "b4e0c295-5379-480c-bdba-c2183992e44c",
   "user": {
     "user_id": "01K8W7CY66TG9YYJQ14EGTDSCQ",
     "verification_status": {
       "fkyc": {
         "state": "initiated"
       },
       "lkyc": {
         "state": "initiated"
       }
     }
   }
 }

Logout Event

📘
Triggered when an existing user logs out of Wert on your website.

 {
   "type": "logout",
   "click_id": "click_id",
   "hpp_session_id": "b4e0c295-5379-480c-bdba-c2183992e44c",
   "user": {
     "user_id": "01K8W7CY66TG9YYJQ14EGTDSCQ",
     "verification_status": {
       "fkyc": {
         "state": "initiated"
       },
       "lkyc": {
         "state": "initiated"
       }
     }
   }
 }

Card Added Event

📘
Triggered when a user adds a new bank card.

 {
   "type": "card_added",
   "click_id": "click_id",
   "hpp_session_id": "b4e0c295-5379-480c-bdba-c2183992e44c",
   "user": {
     "user_id": "01K8W7CY66TG9YYJQ14EGTDSCQ",
     "verification_status": {
       "fkyc": {
         "state": "initiated"
       },
       "lkyc": {
         "state": "initiated"
       }
     }
   }
 }

Verify Start Event

📘
Triggered when a user starts the verification process.

 {
   "type": "verify_start",
   "click_id": "click_id",
   "hpp_session_id": "b4e0c295-5379-480c-bdba-c2183992e44c",
   "user": {
     "user_id": "01K8W7CY66TG9YYJQ14EGTDSCQ",
     "verification_status": {
       "fkyc": {
         "state": "initiated"
       },
       "lkyc": {
         "state": "success"
       }
     }
   }
 }

Verify Retry Event

📘
Triggered when a user needs to re-upload documents to finish verification.

 {
   "type": "verify_retry",
   "click_id": "click_id",
   "hpp_session_id": "b4e0c295-5379-480c-bdba-c2183992e44c",
   "user": {
     "user_id": "01K8W7CY66TG9YYJQ14EGTDSCQ",
     "verification_status": {
       "fkyc": {
         "state": "retry"
       },
       "lkyc": {
         "state": "success"
       }
     }
   }
 }

Verify Failed Event

📘
Triggered when a user needs to re-upload documents to finish verification.

 {
   "type": "verify_failed",
   "reject_type": "<REJECT_TYPE_ENUM>",
   "click_id": "click_id",
   "hpp_session_id": "b4e0c295-5379-480c-bdba-c2183992e44c",
   "user": {
     "user_id": "01K8W7CY66TG9YYJQ14EGTDSCQ",
     "verification_status": {
       "fkyc": {
         "state": "initiated"
       },
       "lkyc": {
         "state": "failed"
       }
     }
   }
 }

Rejection Types (`REJECT_TYPE_ENUM`)

Rejection Category	Rejection Type Value	Description
LKYC Age	`LKYC_FAILED_AGE`	User does not meet the age requirement for LKYC.
FKYC Age	`FKYC_FAILED_AGE`	User does not meet the age requirement for FKYC.
LKYC Country	`LKYC_FAILED_UNSUPPORTED_COUNTRY`	User's country is not supported for LKYC.
FKYC Country	`FKYC_FAILED_UNSUPPORTED_COUNTRY`	User's country is not supported for FKYC.
LKYC State	`LKYC_FAILED_UNSUPPORTED_STATE`	User's specific state/region is not supported for LKYC.
FKYC State	`FKYC_FAILED_UNSUPPORTED_STATE`	User's specific state/region is not supported for FKYC.
LKYC Duplicate	`LKYC_FAILED_DUPLICATE`	An existing LKYC record already exists for this user.
FKYC Duplicate	`FKYC_FAILED_DUPLICATE`	An existing FKYC record already exists for this user.
LKYC General	`LKYC_FAILED_GENERAL`	Generic failure for LKYC that does not fall under specific categories.
FKYC General	`FKYC_FAILED_GENERAL`	Generic failure for FKYC that does not fall under specific categories.
FKYC Spam	`FKYC_FAILED_SPAM`	FKYC attempt flagged as spam or fraudulent activity.

Verify Success Event

📘
Triggered when a user successfully passes KYC verification.

 {
   "type": "verify_success",
   "click_id": "click_id",
   "hpp_session_id": "b4e0c295-5379-480c-bdba-c2183992e44c",
   "user": {
     "user_id": "01K8W7CY66TG9YYJQ14EGTDSCQ",
     "verification_status": {
       "fkyc": {
         "state": "success"
       },
       "lkyc": {
         "state": "success"
       }
     }
   }
 }

Payment Started Event

📘
Triggered when a user initiates a purchase (pressed “Confirm
and Pay”), and a request was sent to the payment acquirer.

 {
   "type": "payment_started",
   "click_id": "click_id",
   "hpp_session_id": "378dbbf4-4c8c-4520-bdc7-d50da9a9486e",
   "order": {
     "id": "01K8VRXKKFDXP63RM1R6XPF0ZX",
     "base": "USDC",
     "base_amount": "21.91339134",
     "quote": "EUR",
     "quote_amount": "20",
     "address": "0x3833b0d65412268d3C06C1a860462AEE96552cD8",
     "transaction_id": null
   },
   "user": {
     "user_id": "01K8K85AR99RMBCCSRM25Z6X9H",
     "verification_status": {
       "fkyc": {
         "state": "progress"
       },
       "lkyc": {
         "state": "success"
       }
     }
   }
 }

Order Complete Event

📘
Triggered when an order receives “Success” status.
For further details on order statuses, see the lifecycle diagram.

 {
   "type": "order_complete",
   "click_id": "click_id",
   "hpp_session_id": "378dbbf4-4c8c-4520-bdc7-d50da9a9486e",
   "order": {
     "id": "01K8VRXKKFDXP63RM1R6XPF0ZX",
     "base": "USDC",
     "base_amount": "21.91339134",
     "quote": "EUR",
     "quote_amount": "20",
     "address": "0x3833b0d65412268d3C06C1a860462AEE96552cD8",
     "transaction_id": "0xbc3e65059d975ee06ef1b61f668eb5a10fcce148881631dba03",
   },
   "user": {
     "user_id": "01K8K85AR99RMBCCSRM25Z6X9H",
     "verification_status": {
       "fkyc": {
         "state": "progress"
       },
       "lkyc": {
         "state": "success"
       }
     }
   }
 }

Order Failed Event

📘
An order receives “Failed” status.
For further details on order statuses, see the lifecycle diagram.

 {
   "type": "order_failed",
   "click_id": "click_id",
   "hpp_session_id": "378dbbf4-4c8c-4520-bdc7-d50da9a9486e",
   "order": {
     "id": "01K8VRXKKFDXP63RM1R6XPF0ZX",
     "base": "USDC",
     "base_amount": "21.91339134",
     "quote": "EUR",
     "quote_amount": "20",
     "address": "0x3833b0d65412268d3C06C1a860462AEE96552cD8",
     "transaction_id": null,
     "error_code": "Contact bank"
   },
   "user": {
     "user_id": "01K8K85AR99RMBCCSRM25Z6X9H",
     "verification_status": {
       "fkyc": {
         "state": "progress"
       },
       "lkyc": {
         "state": "success"
       }
     }
   }
 }

Order Cancelled Event

📘
Triggered when an order receives “Cancelled” status.
For further details on order statuses, see the lifecycle diagram.

 {
   "type": "order_cancelled",
   "click_id": "click_id",
   "hpp_session_id": "378dbbf4-4c8c-4520-bdc7-d50da9a9486e",
   "order": {
     "id": "01K8VRXKKFDXP63RM1R6XPF0ZX",
     "base": "USDC",
     "base_amount": "21.91339134",
     "quote": "EUR",
     "quote_amount": "20",
     "address": "0x3833b0d65412268d3C06C1a860462AEE96552cD8",
     "transaction_id": null
   },
   "user": {
     "user_id": "01K8K85AR99RMBCCSRM25Z6X9H",
     "verification_status": {
       "fkyc": {
         "state": "progress"
       },
       "lkyc": {
         "state": "success"
       }
     }
   }
 }

Transfer Started Event

⚠️
Triggered after 1 network/block confirmation.

 {
   "type": "transfer_started",
   "click_id": "click_id",
   "hpp_session_id": "378dbbf4-4c8c-4520-bdc7-d50da9a9486e",
   "order": {
     "id": "01K8VRXKKFDXP63RM1R6XPF0ZX",
     "base": "USDC",
     "base_amount": "21.91339134",
     "quote": "EUR",
     "quote_amount": "20",
     "address": "0x3833b0d65412268d3C06C1a860462AEE96552cD8",
     "transaction_id": "0xbc3e65059d975ee06ef1b61f668eb5a10fcce148881631dba03",
   },
   "user": {
     "user_id": "01K8K85AR99RMBCCSRM25Z6X9H",
     "verification_status": {
       "fkyc": {
         "state": "progress"
       },
       "lkyc": {
         "state": "success"
       }
     }
   }
 }

Tx Smart Contract Failed Event

⚠️
Only available on smart contract checkout.

📘
A transaction to the smart contract has failed.
For further details on order statuses, see the lifecycle diagram.

 {
   "type": "tx_smart_contract_failed",
   "click_id": "click_id",
   "order": {
     "id": "01K8VRXKKFDXP63RM1R6XPF0ZX",
     "base": "POLSC",
     "base_amount": "21.91339134",
     "quote": "EUR",
     "quote_amount": "20",
     "address": "0x3833b0d65412268d3C06C1a860462AEE96552cD8",
     "transaction_id": "0xbc3e65059d975ee06ef1b61f668eb5a10fcce148881631dba03",
     "partner_data": {
       "sc_address": "0x4d6F96ACc38576de63b353455aC110FafF9bC93D",
       "sc_input_data": "0xd095362f0000690d4c21a2c288a6877d048c05b0b1805c322"
     },
     "fallback_order": {
     	 "id": "01K8VRXKKFDXP63RM1R6XPF0ZX",
     	 "base": "POL",
     	 "base_amount": "21.91339134",
     	 "quote": "EUR",
     	 "quote_amount": "20",
     	 "address": "0x3833b0d65412268d3C06C1a860462AEE96552cD8",
     	 "transaction_id": "" // Will include tx hash if order sending is successful
     }
   },
   "user": {
     "user_id": "01K8K85AR99RMBCCSRM25Z6X9H",
     "verification_status": {
       "fkyc": {
         "state": "progress"
       },
       "lkyc": {
         "state": "success"
       }
     }
   }
 }

Test Event

📘
Triggered by providing a callback URL in the Partner Account/Webhooks tab and pressed “Test” to receive a test webhook.

 {
   "type": "test",
   "click_id": "test_click_id",
   "order": {
     "id": "",
     "base": "POL",
     "base_amount": "21.91339134",
     "quote": "EUR",
     "quote_amount": "20",
     "address": "0x3833b0d65412268d3C06C1a860462AEE96552cD8",
     "transaction_id": "0xbc3e65059d975ee06ef1b61f668eb5a10fcce148881631dba03",
   }
 }

Configuring the webhook endpoint

Wert module lifecycle

Events

Rejection Types (REJECT_TYPE_ENUM)

Rejection Types (`REJECT_TYPE_ENUM`)