Overview
Webhooks enable real-time, event-driven automation by sending instant notifications from Perkstar to your own systems or third-party applications whenever specific events occur. Unlike traditional integrations that poll for changes on a schedule, webhooks push data to you immediately when something happens, allowing for instant reactions and seamless automation.
What you can do with webhooks:
Receive real-time notifications when customers perform actions (register, add card, make purchase)
Trigger automated workflows in your own systems based on loyalty events
Sync loyalty data instantly to custom applications or databases
Build advanced integrations with platforms that aren't natively supported
Create custom business logic that responds to loyalty program activity
Monitor all loyalty events in real-time for analytics or alerting
Tip: Webhooks eliminate delays and manual work by pushing information to your systems the moment events occur. Instead of checking for updates every hour or day, your applications receive instant notifications, enabling immediate customer engagement, real-time reporting, and synchronised systems across your entire business technology stack.
Who should use webhooks:
Developers: Building custom integrations and automation
Technical teams: Implementing advanced workflow automation
IT administrators: Connecting Perkstar to proprietary systems
Advanced users: Creating custom business logic beyond standard integrations
Technical knowledge required:
Understanding of HTTP/HTTPS and REST APIs
Ability to receive and parse JSON data
Basic programming skills (any language that handles HTTP requests)
Access to a web server or cloud function to receive webhook calls
Before You Begin
Requirements:
Active Perkstar account
Account owner or administrator permissions
Webhook support included in your subscription plan (check the Plan section)
Technical knowledge of APIs and web development
What You'll Need:
Technical infrastructure:
A publicly accessible HTTPS endpoint (URL) to receive webhook data
Web server, cloud function, or webhook service (Zapier, Make, n8n)
Ability to parse JSON payloads
(Recommended) Webhook signature verification for security
Development setup:
Testing environment is separate from production
Logging system to track incoming webhooks
Error handling and retry logic
Monitoring alerts for webhook failures
Understanding Webhooks vs. Integrations
Webhooks:
Real-time push notifications
You write custom code to handle events
Maximum flexibility and customisation
Requires technical implementation
Perfect for: Custom systems, unique workflows, real-time requirements
Pre-built Integrations:
Pre-configured connections to popular platforms
No coding required
Limited to available integrations
Easier setup, but less flexible
Perfect for: Standard use cases, non-technical users, common platforms
Use webhooks when:
You need real-time event notifications
You're integrating with custom or proprietary systems
Pre-built integrations don't meet your needs
You want complete control over data processing
You're building advanced automation workflows
Accessing the Webhooks Section
How to Navigate to Webhooks
From your dashboard:
Log in to your Perkstar account
Click Settings (⚙️ icon) in the left-hand menu
Click the Webhooks tab at the top of the Settings screen
Note: The Webhooks screen displays all webhook management tools and options.
Webhooks Screen Layout
The Webhooks section contains two main areas:
Webhooks List (table):
Displays all existing webhooks
Shows URL, Status, and Event Count for each webhook
Quick overview of all active webhook configurations
Add Webhook button:
Creates new webhook configurations
Opens webhook creation popup
Understanding the Webhooks List
Webhooks Table Columns
All configured webhooks appear in a table with the following information:
URL:
The endpoint that receives webhook notifications
Full HTTPS address of your receiving server or service
Status:
Current operational state of the webhook
Enabled: Webhook is active and sending notifications
Disabled: Webhook is paused and not sending notifications
Allows you to temporarily disable webhooks without deleting them
Event Count:
Number of event types this webhook is subscribed to
Higher number = webhook receives more types of notifications
Click on webhook to see which specific events are enabled
Viewing Webhook Details
To view or edit an existing webhook:
Locate the webhook in the Webhooks list
Click on the webhook row
Webhook details popup opens showing full configuration
Details shown:
Complete URL
All subscribed event types with checkboxes
Current status (Enabled/Disabled toggle)
Creation date
Last delivery information (if available)
Edit and Delete options
Creating a New Webhook
Step 1: Prepare Your Endpoint
Warning: Before creating a webhook in Perkstar, ensure your receiving endpoint is ready.
Your endpoint must:
Be publicly accessible via HTTPS (not HTTP)
Accept HTTP POST requests
Return 200 status code for successful receipt
Respond within 5-10 seconds (fast processing)
Parse JSON request body
Handle webhook retries gracefully
Security recommendations:
Use HTTPS (required for security)
Validate webhook signatures (if provided by Perkstar)
Implement rate limiting to prevent abuse
Log all incoming webhooks for debugging
Use firewall rules to restrict access if possible
Example endpoint setup (Node.js/Express):
app.post('/webhooks/perkstar', (req, res) => { // Parse the JSON webhook payload const event = req.body; // Log the webhook for debugging console.log('Received webhook:', event); // Process the event (async recommended) processWebhook(event); // Immediately return 200 to acknowledge receipt res.status(200).send('OK'); });Step 2: Create the Webhook in Perkstar
To add a new webhook:
Navigate to Settings → Webhooks tab
Click the Add webhook button
The Add webhook popup opens
Step 3: Configure Webhook Settings
Enter the webhook URL:
In the URL field at the top of the popup, enter your endpoint address
Must be a complete HTTPS URL
Double-check for typos—incorrect URLs will fail
Select event types:
Below the URL field, you'll see a list of available event types
Each event type has a checkbox
Mark the checkbox for every event you want to receive
Only subscribe to events you actually need (reduces unnecessary traffic)
Step 4: Enable the Webhook
Set webhook status:
Locate the Status toggle button in the popup
Toggle to Enabled (ON position)
If you want to save the webhook but not activate it yet, leave it Disabled
Enabled webhooks:
Immediately begin sending notifications
Will trigger for any subscribed events that occur
Can be disabled later without deleting
Disabled webhooks:
Configuration is saved but no notifications are sent
Useful for testing or temporary pauses
Can be enabled anytime
Step 5: Save the Webhook
To complete webhook creation:
Review all settings (URL, events, status)
Click the Add Webhook button at the bottom of the popup
Webhook is created and added to the Webhooks list
Info: If enabled, the webhook begins sending notifications immediately.
After creation:
New webhook appears in the Webhooks list table
Event Count column shows number of subscribed events
Status column shows Enabled or Disabled
Test the webhook by triggering a subscribed event
Available Event Types
Understanding Event Types
Info: Event types represent specific actions or changes that occur in your Perkstar account. When you subscribe to an event type, your webhook receives a notification every time that event happens.
Common Event Types
Customer Events:
customer.created- New customer registers or is addedcustomer.updated- Customer profile information changescustomer.deleted- Customer is removed from system
Loyalty Card Events:
card.installed- Customer adds card to digital walletcard.updated- Card information or design changescard.deleted- Customer removes card from wallet
Transaction Events:
transaction.created- Points, stamps, or cashback addedtransaction.completed- Transaction finalized and confirmedtransaction.reversed- Transaction cancelled or points deducted
Reward Events:
reward.issued- Customer earns a rewardreward.redeemed- Customer uses/claims a rewardreward.expired- Unclaimed reward expires
Push Notification Events:
push.sent- Push notification delivered to customerpush.opened- Customer opens push notificationpush.failed- Push notification delivery failed
Feedback Events:
feedback.received- Customer submits feedback or ratingfeedback.updated- Feedback is modified
Referral Events:
referral.created- New referral initiatedreferral.completed- Referral successfully converts
Note: Available event types may vary by plan and Perkstar version. Check the Add webhook popup for the complete list of events available to your account.
Choosing Which Events to Subscribe To
Best practices for event selection:
Start minimal:
Only subscribe to events you actively need
Fewer events = simpler logic and less data to process
You can always add more events later
Common starting combinations:
Customer activity tracking: customer.created, transaction.completed
Real-time CRM sync: customer.created, customer.updated, transaction.created
Reward automation: reward.issued, reward.redeemed
Engagement monitoring: card.installed, push.opened, feedback.received
Consider event volume:
transaction.created can trigger many times per day (high volume)
customer.created triggers less frequently (lower volume)
Ensure your system can handle the expected webhook volume
Group-related events:
Tip: If you need one lifecycle event, you often need the complete set. Example: customer.created, customer.updated, customer.deleted together. This ensures your system stays synchronised with all changes.
Webhook Payload Structure
What Data is Sent
:::info When an event occurs, Perkstar sends an HTTP POST request to your webhook URL containing JSON data about the event. :::
Standard payload structure:
{ "event_type": "customer.created", "event_id": "evt_abc123xyz", "timestamp": "2025-10-14T15:30:00Z", "account_id": "acc_12345", "data": { // Event-specific data here } }Common Payload Fields
event_type (string):
Identifies which event occurred
Example: "customer.created", "transaction.completed"
Use this to route webhooks to appropriate handlers
event_id (string):
Unique identifier for this specific event
Use for idempotency (detecting duplicate deliveries)
Include in logs for troubleshooting
timestamp (ISO 8601 datetime):
When the event occurred
Example: "2025-10-14T15:30:00Z"
UTC timezone
account_id (string):
Your Perkstar account identifier
Useful if one endpoint handles multiple accounts
Can be used to route to correct database/tenant
data (object):
Event-specific details
Structure varies by event type
Contains the actual payload (customer info, transaction details, etc.)
Example Payloads by Event Type
customer.created:
{ "event_type": "customer.created", "event_id": "evt_abc123", "timestamp": "2025-10-14T15:30:00Z", "account_id": "acc_12345", "data": { "customer_id": "cust_67890", "email": "customer@example.com", "phone": "+1234567890", "name": "John Smith", "created_at": "2025-10-14T15:30:00Z" } }transaction.completed:
{ "event_type": "transaction.completed", "event_id": "evt_def456", "timestamp": "2025-10-14T16:45:00Z", "account_id": "acc_12345", "data": { "transaction_id": "txn_11111", "customer_id": "cust_67890", "card_id": "card_22222", "type": "points_added", "amount": 50, "balance_after": 350, "timestamp": "2025-10-14T16:45:00Z" } }reward.issued:
{ "event_type": "reward.issued", "event_id": "evt_ghi789", "timestamp": "2025-10-14T17:00:00Z", "account_id": "acc_12345", "data": { "reward_id": "rwd_33333", "customer_id": "cust_67890", "reward_type": "free_item", "reward_name": "Free Coffee", "issued_at": "2025-10-14T17:00:00Z", "expires_at": "2025-11-14T23:59:59Z" } }Handling Webhook Payloads
Best practices for payload processing:
Validate payload structure:
Check that required fields exist
Verify data types are correct
Handle missing or unexpected fields gracefully
Use event_id for idempotency:
Store processed event_ids to detect duplicates
If you receive same event_id twice, skip processing
Prevents duplicate actions (double-charging, duplicate records)
Parse data carefully:
Use JSON parser appropriate for your language
Handle parsing errors (malformed JSON)
Validate data before using it in business logic
Respond quickly:
Warning: Return 200 status immediately upon receipt. Process webhook asynchronously (queue for processing). Don't perform long operations before responding. Perkstar will retry if you don't respond quickly.
Example idempotency check (pseudocode):
async function handleWebhook(payload) { // Check if we've already processed this event if (await isEventProcessed(payload.event_id)) { console.log('Duplicate event, skipping'); return; } // Mark as processed before doing work await markEventProcessed(payload.event_id); // Now process the event await processEvent(payload); }Testing Your Webhooks
Why Testing is Critical
Before relying on webhooks in production:
Verify your endpoint receives webhooks correctly
Ensure payload parsing works as expected
Confirm your business logic handles events properly
Identify and fix any issues before they affect customers
Testing Strategies
1. Use webhook testing tools:
Webhook.site: Free service that displays incoming webhooks
RequestBin: Temporary endpoint for inspecting webhook payloads
Postman: Send test requests to your endpoint manually
2. Create test events in Perkstar:
Register a test customer
Perform a test transaction
Trigger events you've subscribed to
Verify webhooks arrive at your endpoint
3. Check your logs:
Review server logs for incoming POST requests
Verify JSON payload structure
Check for any parsing errors
Confirm business logic executes correctly
4. Test error scenarios:
What happens if your endpoint is down?
How does your system handle malformed payloads?
Does idempotency work (send duplicate event_id)?
Can your system recover from temporary failures?
Using Webhook.site for Testing
Quick test before production:
Go to https://webhook.site
Copy the unique URL provided
In Perkstar, create a test webhook with that URL
Subscribe to an event like customer.created
Create a test customer in Perkstar
Check webhook.site—you'll see the webhook payload
Review the JSON structure and data fields
Benefits:
No coding required
See webhooks in real-time
Inspect headers and payload
Perfect for understanding payload structure before building
Managing Existing Webhooks
Editing a Webhook
To modify an existing webhook:
Navigate to Settings → Webhooks tab
Click on the webhook you want to edit in the list
The webhook details popup opens
Make your changes:
Update the URL if endpoint changed
Check or uncheck event types
Toggle status (Enable/Disable)
Click Save or Update button
Info: Changes take effect immediately.
When to edit webhooks:
Endpoint URL changes (new server, different service)
You need additional event types
You want to reduce events to lower volume
Temporarily disabling for maintenance
Enabling and Disabling Webhooks
To temporarily disable a webhook:
Click on the webhook in the list
Toggle the Status switch to Disabled
Click Save
Note: Webhook configuration is preserved but no notifications sent.
To re-enable a webhook:
Click on the webhook
Toggle Status to Enabled
Click Save
Tip: Webhook immediately resumes sending notifications.
Use cases for disabling:
Endpoint maintenance or server updates
Troubleshooting webhook issues
Temporary pause during testing
Seasonal business closure
Benefits vs. deleting:
Configuration is preserved (URL, events)
Easy to re-enable later
No need to reconfigure from scratch
Can disable/enable multiple times
Deleting a Webhook
To permanently remove a webhook:
Click on the webhook in the list
Locate the Delete button in the details popup
Confirm deletion when prompted
Webhook is removed from the list
After deletion:
Webhook stops sending notifications immediately
Configuration cannot be recovered (must recreate)
Endpoint will no longer receive any requests from Perkstar
Does not affect any other webhooks
When to delete webhooks:
Endpoint is permanently decommissioned
Integration project cancelled
Webhook was created for testing only
Consolidating multiple webhooks into one
Before deleting:
Export webhook configuration for documentation
Notify team members who may rely on webhook
Ensure no critical workflows depend on the webhook
Consider disabling first to test impact before permanent deletion
Security Best Practices
HTTPS Requirements
Warning: Always use HTTPS, never HTTP. HTTP webhooks send data unencrypted over the internet. Anyone can intercept and read sensitive customer data. Perkstar may require HTTPS for all webhooks.
Setting up HTTPS:
Use cloud providers with built-in HTTPS (AWS, Azure, Google Cloud)
Get free SSL certificate from Let's Encrypt
Use webhook services that provide HTTPS endpoints
Never deploy production webhooks over HTTP
Webhook Signature Verification
info: Perkstar may include a cryptographic signature in webhook headers, allowing you to verify the webhook actually came from Perkstar and wasn't forged.
Why it matters:
Prevents attackers from sending fake webhooks to your endpoint
Ensures data integrity (webhook wasn't modified in transit)
Required for processing sensitive actions (payments, account changes)
How to verify (pseudocode):
function verifyWebhookSignature(payload, signature, secret) { // Calculate expected signature const expectedSignature = hmacSHA256(payload, secret); // Compare with received signature return timingSafeCompare(signature, expectedSignature); } // In your webhook handler if (!verifyWebhookSignature(req.body, req.headers['x-webhook-signature'], WEBHOOK_SECRET)) { return res.status(401).send('Invalid signature'); }Check Perkstar documentation:
Signature header name
Hashing algorithm used (HMAC-SHA256 typical)
Where to find/configure webhook secret
Example verification code for your language
Access Control
Restrict endpoint access:
Use firewall rules to limit IPs that can access your webhook endpoint
Implement rate limiting (prevent abuse if URL is discovered)
Require authentication headers in addition to signature verification
Log all webhook requests for security auditing
Don't expose sensitive data:
Don't include API keys or passwords in webhook URLs
Use POST body for data, not URL query parameters
Ensure error messages don't leak system information
Sanitize logs to remove sensitive customer data
Error Handling and Logging
Comprehensive logging:
Log all incoming webhooks with timestamp and event_id
Record payload for debugging (be mindful of data privacy)
Log processing outcomes (success, failure, errors)
Set up alerts for repeated webhook failures
Graceful error handling:
Catch and log all errors during webhook processing
Return 200 even if business logic fails (acknowledge receipt)
Use dead letter queue for failed webhook processing
Retry failed operations with exponential backoff
Example error handling:
app.post('/webhooks/perkstar', async (req, res) => { try { // Always respond quickly res.status(200).send('OK'); // Process asynchronously await processWebhook(req.body); } catch (error) { // Log error but don't fail the webhook logger.error('Webhook processing failed', { eventId: req.body.event_id, error: error.message }); // Add to retry queue await retryQueue.add(req.body); } });Advanced Webhook Patterns
Multiple Webhooks for Different Purposes
You can create multiple webhooks with different configurations.
Example architecture:
Webhook 1: Customer events → Syncs to CRM (customer.created, customer.updated)
Webhook 2: Transaction events → Updates accounting system (transaction.completed)
Webhook 3: All events → Sends to analytics platform (all event types)
Webhook 4: Reward events → Triggers fulfillment workflow (reward.issued, reward.redeemed)
Benefits:
Separation of concerns (different systems handle different events)
Independent failure (one webhook failing doesn't affect others)
Easier debugging and monitoring
Different security/authentication per webhook
Fan-out Pattern
Tip: Send webhooks to message queue for distribution. Your webhook endpoint receives Perkstar webhooks and publishes to message queue (RabbitMQ, AWS SQS, etc.). Multiple consumers process events independently.
Benefits:
Scalability (multiple workers process webhooks)
Reliability (queue stores events if consumers are down)
Flexibility (add new consumers without changing webhook)
Decoupling (webhook receipt separate from processing)
Webhook Retry Logic
Understanding webhook delivery:
Perkstar may retry failed webhooks automatically
Retries occur if your endpoint doesn't return 200 status
Retry timing: typically immediate, 1 minute, 5 minutes, 30 minutes
After maximum retries, webhook may be marked as failed
Your endpoint should:
Return 200 quickly (under 5 seconds)
Handle duplicate deliveries gracefully (idempotency)
Not rely on synchronous processing
Queue webhooks for asynchronous processing
Common Use Cases
Real-Time CRM Synchronization
Goal: Keep CRM instantly updated with loyalty program activity
Setup:
Subscribe to: customer.created, customer.updated, transaction.completed
Webhook sends data to CRM API
Customer records stay synchronized in real-time
Benefits:
Sales team sees loyalty activity immediately
No manual data export/import
Complete customer view across systems
Custom Reward Fulfillment
Goal: Automatically fulfill rewards outside Perkstar
Setup:
Subscribe to: reward.issued, reward.redeemed
Webhook triggers fulfillment system (send email with code, create shipping order, etc.)
Confirmation sent back to Perkstar
Benefits:
Instant reward delivery
Integration with external systems (e-gift cards, shipping APIs)
Automated workflow reduces manual work
Business Intelligence Dashboards
Goal: Real-time analytics dashboard with loyalty metrics
Setup:
Subscribe to: All event types
Webhook sends data to analytics database
Dashboard queries database for live metrics
Benefits:
Real-time visibility into loyalty program performance
Custom reporting beyond Perkstar's built-in analytics
Combine loyalty data with other business metrics
Customer Engagement Automation
Goal: Trigger personalised marketing based on loyalty behaviour
Setup:
Subscribe to: transaction.completed, reward.issued, feedback.received
Webhook triggers marketing automation platform
Personalised follow-up messages sent automatically
Benefits:
Immediate response to customer actions
Personalised engagement improves loyalty
Automated workflow saves marketing team time
Troubleshooting Webhooks
Webhook Not Receiving Events
Problem: You've created a webhook but no notifications arrive
Troubleshooting steps:
Verify webhook is enabled:
Check Status column in webhooks list
Open webhook details to confirm Status toggle is ON
Enable if it's disabled
Check URL is correct:
Open webhook details and verify URL
Ensure no typos or extra spaces
Confirm it's the correct endpoint (not localhost or internal URL)
Test endpoint accessibility:
Use curl or Postman to send test POST request to your URL
Ensure endpoint is publicly accessible
Check firewall isn't blocking requests from Perkstar IPs
Trigger a test event:
Manually perform action that should trigger subscribed event
Example: If subscribed to customer.created, create a test customer
Check if webhook arrives at your endpoint
Review event subscriptions:
Open webhook details
Verify you've checked boxes for events you want
Event Count should match expected number
Endpoint Returning Errors
Problem: Webhooks arrive but your endpoint returns 4xx or 5xx status codes
Common causes and solutions:
Invalid JSON parsing:
Ensure your code parses JSON correctly
Handle malformed JSON gracefully
Log the raw payload for debugging
Authentication/authorization issues:
If your endpoint requires auth, ensure webhook can bypass or has credentials
Verify signature checking logic is correct
Check for expired tokens or certificates
Timeout errors:
Your endpoint must respond within 5-10 seconds
Process webhooks asynchronously (return 200 immediately, then process)
Use message queue for long-running operations
Internal server errors:
Check your application logs for error details
Fix bugs in webhook handling code
Add comprehensive error handling and logging
Duplicate Webhook Deliveries
Problem: Same event delivered multiple times
Causes:
Your endpoint didn't return 200 fast enough (Perkstar retried)
Network issues caused retry
This is normal behavior—webhooks should be idempotent
Solution: Implement idempotency using event_id:
// Track processed events const processedEvents = new Set(); function handleWebhook(payload) { // Check if already processed if (processedEvents.has(payload.event_id)) { console.log('Duplicate event, skipping'); return; } // Mark as processed processedEvents.add(payload.event_id); // Process the event processEvent(payload); }For persistent storage:
Store event_ids in database
Check database before processing
Set TTL on stored event_ids (delete after 30 days)
Webhook Payloads Missing Expected Data
Problem: Webhook arrives but doesn't contain fields you need
Troubleshooting:
Check payload structure:
Log the full payload to see what's actually sent
Compare with expected structure
Ensure you're looking in correct nested object
Verify event type:
Different events have different payload structures
Ensure you're subscribing to correct event for data you need
Check Perkstar documentation for payload schemas
Handle null/missing fields:
Not all fields may be present in all events
Implement null checks in your code
Use default values for optional fields
API version:
Webhook payload structure may vary by API version
Check if you need to upgrade or change version
Contact support for payload documentation
Best Practices Summary
Webhook Implementation Checklist
Security:
✅ Use HTTPS endpoints only
✅ Implement webhook signature verification
✅ Restrict access with firewall rules
✅ Never expose API keys in webhook URLs
✅ Log all webhooks for security auditing
Reliability:
✅ Return 200 status immediately (under 5 seconds)
✅ Process webhooks asynchronously
✅ Implement idempotency using event_id
✅ Use message queue for robust processing
✅ Set up monitoring and alerting for failures
Performance:
✅ Acknowledge receipt quickly (return 200)
✅ Queue webhooks for background processing
✅ Scale horizontally if webhook volume is high
✅ Use caching where appropriate
✅ Optimize database queries in webhook handlers
Testing:
✅ Test with webhook.site before production
✅ Create test webhooks in separate environment
✅ Verify idempotency works correctly
✅ Test error scenarios and recovery
✅ Monitor test webhooks during initial rollout
Maintenance:
✅ Document all webhooks and their purposes
✅ Review webhook logs regularly
✅ Disable unused webhooks to reduce noise
✅ Update endpoint URLs when infrastructure changes
✅ Audit webhook subscriptions quarterly
Frequently Asked Questions
What's the difference between webhooks and the API key?
The API key allows you to call Perkstar's API to request data or perform actions. Webhooks push data to you automatically when events occur. API = you pull data. Webhooks = Perkstar pushes data to you.
Can I have multiple webhooks with the same URL?
Yes, but it's usually unnecessary. You can create one webhook subscribed to multiple event types. Multiple webhooks to the same URL might result in duplicate deliveries if event subscriptions overlap.
What happens if my endpoint is down?
Perkstar will retry delivery several times over minutes to hours. If all retries fail, the webhook may be marked as failed. You'll need to re-enable it and may miss events during downtime. Use a message queue for reliability.
How can I test webhooks without affecting production data?
Use a test/sandbox Perkstar account if available, or create test customers/transactions clearly marked as tests. You can also use webhook.site to inspect payloads before building your endpoint.
Can I see a log of webhooks that were sent?
Webhook delivery logs may be available in the webhook details view, showing recent deliveries, timestamps, and success/failure status. Check the details page of each webhook for delivery history.
What should I do if I'm getting too many webhooks?
Unsubscribe from event types you don't need, or implement filtering in your endpoint to ignore certain events. You can also batch process webhooks instead of handling each individually.
Can I use localhost URLs for testing?
No. Localhost URLs (http://localhost:3000) are not publicly accessible. Use ngrok, webhook.site, or deploy to a cloud service with a public URL for testing.
How do I know which events I should subscribe to?
Start with the minimum events needed for your use case. Common starting point: customer.created and transaction.completed. You can always add more events later as needs evolve.
What's the maximum payload size for webhooks?
Webhook payloads are typically small (under 10KB) as they contain concise event data, not large files. If you need full customer history, use webhooks to trigger API calls that fetch detailed data.
Can webhooks send data to internal (private network) endpoints?
No. Webhooks require publicly accessible HTTPS URLs. For internal systems, use a public-facing proxy or API gateway that forwards to internal systems securely.
How quickly are webhooks delivered after an event?
Webhooks are typically delivered within seconds of the event occurring. Exact timing depends on system load, but expect near-real-time delivery under normal conditions.
What if I receive a webhook for an event I don't recognise?
Log the full payload for investigation. Perkstar may add new event types, or you may have subscribed to events accidentally. Check the event_type field and compare with the documentation.
Can I filter webhooks by customer segment or card type?
Filtering is typically not available at the webhook subscription level. You'll receive webhooks for all events of subscribed types and must filter in your endpoint code based on payload data.
How do I update my webhook URL without losing configuration?
Edit the existing webhook, change the URL, and save. All event subscriptions and settings are preserved. The new URL immediately receives future webhooks.
Are webhooks included in all plans?
Webhook availability depends on your subscription plan. Check your Plan section to see if webhooks are included and how many you can create. Higher-tier plans typically offer more webhooks.
Tip: Need more help? Contact Perkstar support for webhook troubleshooting, payload documentation, implementation guidance, or technical questions about event types and delivery.