🪝Listen for Submerchant Registration

Webhooks are available for the KYB lifecycle

Webhooks allow you to subscribe to events from Coinflow about the sub-merchant KYB lifecycle


  1. To set up Webhooks for your application go to the Coinflow Admin Dashboard > Webhooks:
  1. Copy your Webhook Validation Key.


Keep this Validation Key secret, but if it gets leaked you can easily regenerate it.

  1. Enter your webhook settings configuration. All of the relevant event types prefixed with Sub-Merchant
  • Enter a URL route to your server endpoint
  • Sub-merchant event types are only available in Version 2
  • Select the event types that should post notification (see addendum for event type detail)
  1. On your server, create a route that accepts a POST request on that url and route


Make sure the Authorization header in this request is equal to your Verification Key to validate that this request is coming from Coinflow.

router.post('/submerchant-webhook', async (req, res) => {  
	try {
    const {data} = req.body;
    const {merchantId} = data;
    console.log(`Merchant KYB: ${merchantId}`);
    const authHeader = req.get('Authorization');
    // Authorize using your validation key
    if (authHeader !== process.env.COINFLOW_VALIDATION_KEY)
      throw new ControllerError('User not allowed', 401);
    else handleEvent() // react to event
  } catch (e) {  
    handleError(res, e);  


Webhooks will retry until your server returns a 200 response code

or until it times out after 36 hours. Webhooks will also time out after 5 seconds without a response and will retry, so make sure your server responds within 5 seconds.

  1. The webhooks will contain the following data:
  eventType: string,
  category: 'KYC',
  created: string,
  data: {
  	merchantId: string,
  	email: string,
  1. Done! Try listening to different event types by subscribing to the different options below

Sub-merchant Event Types

Event TypeDescription
Sub-merchant KYB CreatedKYB information was submitted for the sub-merchant and is awaiting processing
Sub-merchant KYB SuccessThe sub-merchant's KYB application has been approved
Sub-merchant KYB FailureThe sub-merchant's KYB application did not pass (and probably needs additional information)