Webhook Integration Guide for Subscription Management
This guide is intended for developers looking to integrate real-time subscription event notifications into their applications. With our webhook system, you’ll receive automated POST requests to your designated URL for events like new sign-ups, renewals, and payment failures.
Getting Started
A webhook allows our system to send real-time updates 📡 to your application. We’ll POST a JSON payload to your specified endpoint whenever a relevant subscription event occurs.
Step 1: Create/Edit Subscription & Plug in Your Webhook URL
You can set up a webhook URL in the Flash web app either while creating a new subscription or by editing an existing subscription:
When creating a new subscription:
Head over to New Subs > Create a Subscription Plan
Make sure to click on the “Use Advanced Webhook Features” checkbox to make the Webhook Url field appear
Input your Webhook URL in the form when creating the subscription
After creating the Subscription, you will receive a url with the subscription and the subscription key. You can use this key to decode and verify the JWT token that comes with our event (see guide below).
When you have already created a subscription:
Head over to My Subscriptions
Select the subscription you want to add webhooks for
Click on “Edit Subscription”
Fill in/modify the Webhook Url field
The subscription key is also visible in this screen and can be used to decode and verify the JWT token that comes with our event (see guide below).
Step 2: Configure Your Webhook Endpoint
To receive webhook notifications, set up a POST endpoint in your application:
Ensure it accepts JSON payloads.
Process the data based on the event type and take appropriate actions.
Security Tip: Always use HTTPS to secure webhook transmissions.
Responding to Webhook Calls
Your webhook endpoint should respond with a 200 OK status to acknowledge receipt of the event. If no response or an error is received, we may retry the notification.
Event Types
The system triggers the following events, each sending a POST request with event data to your webhook:
1. User Signed Up (name='user_signed_up', id=1)
Triggered when a user subscribes to a plan. The payload includes details like the user's public key, plan, and transaction info.
The data sent to your webhook URL will be structured as a JSON object containing two primary fields: eventType and data. The eventType field indicates the type of event, while the data field contains event-specific information.
Here's a breakdown of the data you can expect for each event type:
Common Fields Across All Event Types:
public_key: The user's public key.
name: The user's name.
email: The user's email address.
about: A brief description of the user.
picture_url: The URL to the user's profile picture.
user_plan: The subscription plan the user has signed up for.
user_plan_id: The subscription plan id the user has signed up for.
Event-Specific Fields:
signup_date: The date the user signed up (only for user_signed_up).
next_payment_date: The next payment date for the subscription (only for renewal_successful).
failed_payment_date: The date of the failed payment (only for renewal_failed).
transaction_id: The ID of the transaction (varies by event type).
transaction_amount: The payment amount of the transaction(all same)
transaction_currency: The currency of the transaction(all same)
transaction_date: The date of the transaction (varies by event type).
Securing Webhooks with JWT
All webhooks include a JWT token in the Authorization header, allowing you to verify that the event is coming from Flash. You can decode and verify this token using the subscription key provided in the web app.
To verify the token, decode it using your subscription key and the HS256 algorithm.
Handling Webhooks
Your webhook should always respond with a 200 OK status after processing the event. Failure to do so may cause the system to retry the notification.
Best Practices
Idempotency: Ensure that your webhook handler can process the same event more than once without causing errors or duplicate actions.
Logging: Implement logging for all webhook events to make troubleshooting easier.
FAQ
Can I set up multiple webhook URLs?
Can I set up multiple webhook URLs?
Currently, we support one webhook URL per subscription. You can handle different events with routing logic in your app.
What if I stop receiving webhooks?
Ensure your endpoint is correctly configured and reachable. If the issue persists, contact our support team.
Conclusion
By integrating our webhook system, you can stay updated on key subscription events in real time, helping automate and optimize your processes. Feel free to contact our developer support team if you need any help.
Webhook Usage - full example
Assuming your webhook URL is https://webhook , you can refer to the following code:
const jwt = require('jsonwebtoken');
app.post('/webhook', (req, res) => {
const data = req.body; // Extract JSON data from the request
const authHeader = req.headers.authorization;
const token = authHeader && authHeader.split(' ')[1];
if (!token) {
return res.status(401).json({ error: 'No token provided' });
}
// Verify and decode the JWT token
const secret = 'your_secret_key';
jwt.verify(token, secret, (err, decodedToken) => {
if (err) {
return res.status(401).json({ error: 'Invalid token' });
}
const { version, eventType, user_public_key } = decodedToken;
// Process the data as needed
console.log('User public key:', user_public_key);
console.log('Event Type:', eventType);
});
// Access fields from the JSON payload
const userPublicKey = data.data.public_key;
const userName = data.data.name;
const userEmail = data.data.email;
// Process the data...
res.json({ ok: true });
});
