🪝Webhooks

Webhooks allow your application to subscribe to updates from Coinflow and react when users make purchases.

Use this recipe for a guided walkthrough

Setup

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

• Production
• Sandbox

2. Copy your Webhook Validation Key.

🚧

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

3. Enter your webhook settings configuration. In this example, we are going to listen for all successful credit card payments & Coinflow Credit purchases:

• Enter a URL route to your server endpoint
• Select the webhook version (this will determine available event types and payload format)

Legacy: the original webhook format that will only notify when Coinflow Credits are minted

Version 1 or Version 2 (Recommended): updated webhook format that provides multiple event types & more payload detail

• Select the event types that should post notification (see addendum for event type detail)

4. In 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 Validation Key to validate that this request is coming from Coinflow.

router.post('/credits-purchase-webhook', async (req, res) => {  
	try { 
    // Version 2 Coinflow webhook response
    const {data} = req.body;
    const {webhookInfo, wallet, subtotal} = data;
    
    console.log(`Coinflow purchase from ${wallet}`);
    
    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 handlePurchase() // react to purchase
    
    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.

5. The format of the webhook request data will vary based on selected version:

{
  signature: string,
  wallet: string,
  webhookInfo: object,
  subtotal: {cents: number},
  fees: {cents: number},
  gasFees: {cents: number},
  total: {cents: number},
  id: string,
}

{
  eventType: string,
  created: string, // UTC ISO string
  data: object,
}

6. Configure your CoinflowPurchase component:

Add the webhookInfo property to your CoinflowPurchase component. That information will be passed as the webhookInfo property in the webhook your server will receive.

<CoinflowPurchase
	...
  webhookInfo={{item: 'sword'}}
/>

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

Event Types

• Credits Minted/Settled (Popular): The credits have been minted for the transaction or USDC has been sent
• Card Payment Authorized (Popular): the credit card payment has been authorized for the transaction

V1 Event Types

V2 Event Types