🪝 Seller Webhooks

Before You Start Implementing Webhooks

In order to respond in a timely manner, we suggest setting up a queue to process webhook payloads asynchronously. Your server can respond when it receives the webhook, and then process the payload in the background without blocking future webhook deliveries. Background processing of webhooks is preferred over inline processing.

Background Processing vs Inline Processing

Inline processing involves executing tasks immediately within the current execution context, potentially leading to longer response times. Background processing involves deferring tasks asynchronously, placing them in a queue for later execution. This allows the application to quickly respond to initial requests without waiting for the task to complete.

How should I handle webhook requests?

When receiving a request, it’s essential to be attentive regarding three key issues:

1. Quickly respond to webhook requests

• If an incoming webhook triggers lengthy processing in your system, we recommend you create a processing queue for events. If you don’t implement a process, a timeout may result, and you will receive a webhook retry.

2. Place importance on responsiveness over availability

• As the handler of incoming webhooks, ensuring continuous availability is paramount. Fortunately, the response to a webhook doesn’t need to include the processing results in it. Your setup can acknowledge the webhook request initially and process it later, facilitated by introducing queues between receipt and processing.

3. Duplicate incoming events

• We can’t guarantee that webhook messages will be delivered only once, so it’s essential to include a mechanism that prevents duplicated events.

Webhook Security Best Practices

• Keep your API Key secure
• Always check the incoming webhook’s authorization against your API key
• Validate the data structure of the message

Overview

Webhooks allow you to subscribe to events from Coinflow about when a seller has registered their account.

Implementation

1. Navigate to your marketplace dashboard

• Production
• Sandbox

2. Copy your Webhook Validation Key.

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

3. Select Version 2

4. Select the event types to listen to.

• For seller registration events, select:

  • Sub-Merchant KYB Created, Sub-Merchant KYB Success, Sub-Merchant KYB Failure

• For sub-merchant onboarding progress, select the following. See Onboarding Webhooks for when each fires and how to handle it:

  • Sub-merchant Application Submitted, Sub-merchant Application Approved, Sub-merchant Application Declined, Sub-merchant RFI Sent, Sub-merchant RFI Submitted, Sub-merchant Bank Account Rejected
  

5. Enter a URL route to your server endpoint

6. In your server, create a route that accepts a POST request on that url and route

🚧 Ensure that the Authorization header in this request matches your Validation Key to verify its origin as Coinflow.

router.post('/submerchant-webhook', async (req, res) => {  
	try {
    const {data} = req.body;
    // merchantId = the seller's id
    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
    
    res.sendStatus(200);
  } 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.

7. The webhooks will contain the following data:

{
  eventType: 'Sub-merchant KYB Created' | 'Sub-merchant KYB Success' | 'Sub-merchant KYB Failure',
  category: 'KYC',
  created: string,
  data: {
    merchantId: string,
    email: string,
  },
}

Sub-merchant onboarding events carry the sub-merchant’s onboarding status instead of an email:

{
  eventType:
    | 'Sub-merchant Application Submitted'
    | 'Sub-merchant Application Approved'
    | 'Sub-merchant Application Declined'
    | 'Sub-merchant RFI Sent'
    | 'Sub-merchant RFI Submitted'
    | 'Sub-merchant Bank Account Rejected',
  category: 'KYC',
  created: string,
  data: {
    merchantId: string,
    // Same value GET /onboarding returns at the time of the event
    status: 'not_started' | 'in_progress' | 'submitted' | 'action_required' | 'approved' | 'declined',
    timestamp: string, // ISO 8601
    rfiId?: string, // Only on Sub-merchant RFI Sent and Sub-merchant RFI Submitted
  },
}

8. Done! Try listening to different event types by subscribing to the different options below

Event Types

📘 Sub-merchant onboarding events are not sent for a sub-merchant whose webhook settings turn off forwarding to its parent.