🪝Webhooks

Webhooks allow you to subscribe to events from Coinflow about the lifecycle of subscriptions

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. All of the relevant event types prefixed with Subscription:

• Enter a URL route to your server endpoint
• Subscription event types are only available in Version 2
• 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 Verification Key to validate that this request is coming from Coinflow.

router.post('/subscription-webhook', async (req, res) => {  
	try {
    const {data} = req.body;
    const {webhookInfo, wallet, amount, planCode} = data;
    
    console.log(`Coinflow subscription (${planCode})  for ${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 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.

5. The webhooks will contain the following data:

{
  eventType: string,
  category: 'Subscription',
  created: string,
  data: {
  	planCode: string,
  	planName: string,
    subscriptionId: string;
  	wallet: string,
  	amount: {cents: number},
  	interval: string,
  	fundingMethod: string,
  	webhookInfo: object | undefined | null,
  	reason?: string,
	},
}

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

Subscription Event Types

Settlement Webhook Events

Settled Webhooks will fire on each run of the subscription. This allows you to track which payments are for which subscription plans: Settled events will include an additional parameter subscription which will include all the subscription information in the following format:

{
  "eventType": "Settled",
  "created": "2024-02-09T16:45:28.295Z",
  "data": {
    "id": "a713d287-f12b-4394-a446-309319514a4b",
    "signature": "2imzvkcr5GzhusDR5NbVB2gSgT8MqG2g6jwuw7knaJ5VZKRQpjapUZLxeptf1uLPTqRdCnsDczNxi1u1oEA3mTaE",
    "wallet": "BDbksKYryFU4qf6DyHRTQwB9S8R2uYQbWJ2WRY1yAVYZ",
    "webhookInfo": {
      "item": "sword"
    },
    "subtotal": {
      "cents": 100
    },
    "fees": {
      "cents": 39
    },
    "gasFees": {
      "cents": 0
    },
    "total": {
      "cents": 139
    },
    "subscription": {
      "customer": "644fd1e897fc6c287dd1a408",
      "merchant": "63be0caa4ecdc006e6a7e35c",
      "plan": {
        "amount": {
          "cents": 100,
          "currency": "USD"
        },
        "merchant": "63be0caa4ecdc006e6a7e35c",
        "name": "basic",
        "code": "basic",
        "interval": "Monthly",
        "description": "this is the basic plan",
        "active": true,
      },
      "fundingMethod": "Card",
      "reference": "a713d287-f12b-4394-a446-309319514a4b",
      "nextPaymentAt": "2024-03-09T16:45:26.309Z",
      "status": "Active",
      "webhookInfo": {
        "item": "sword"
      },
      "createdAt": "2024-02-09T16:45:26.311Z",
      "updatedAt": "2024-02-09T16:45:26.311Z",
    }
  }
}

Questions

1. Will the subscription id change on renewal?
   No. The subscription id remains the same if the subscription is renewed. A new subscription id is generated only if a payment fails, or the subscription needs to be renewed (meaning it hasn't been paid for). Only the id associated with the overall purchase will change each time a purchase is made.
2. When will I get notified of the cancellation?
   The webhooks are fired immediately once the end user makes or cancels their subscription. The webhook will not be triggered again once their subscription period has expired.