Custom Webhook Integration for Email/SMS Platforms
Skio’s Integration Webhooks let you receive real-time subscription events—perfect for email or SMS platforms. It works like our Klaviyo integration but sends events directly to your own webhook endpoi
The Skio Integration Webhook system allows you to receive real-time subscription events from our platform. This integration follows our standard event tracking system, similar to our Klaviyo integration, but with the flexibility of sending events to your own webhook endpoint.
Before you get started, Skio will set up a new integration card for your development store. Please reach out to the Skio team with the name of the store you’re using, and we’ll add the integration section so you can begin testing.
Setup Process
1. Integration Configuration
Navigate to your Skio dashboard
Go to the Integrations section
Select your brand as your integration type
Provide your webhook URL where you want to receive the events
Configure which events you want to receive by adding event triggers

2. Event Payload Structure
Each webhook event will be sent as a POST request to your endpoint with the following structure:
type WebhookPayload = {
eventName: string; // The type of event (see Events section)
eventTriggerSettings?: { // Optional settings specific to the trigger
daysBefore?: number; // For events like billing reminders
};
vendor: string; // The integration vendor (e.g., "canopy", "bloomreach")
properties: { // Event-specific properties
// Common properties included in all events
email: string;
subscriptionId?: string;
status?: string;
// ... other properties depending on the event type
};
domain: string; // Your shop's domain
}
3. Available Events
Here are the key subscription events you can receive:
Subscription Lifecycle Events
subscriptionCreated
: When a new subscription is createdsubscriptionCancelled
: When a subscription is cancelledsubscriptionReactivated
: When a cancelled subscription is reactivatedsubscriptionPaused
: When a subscription is pausedsubscriptionUnpaused
: When a subscription is unpausedsubscriptionSkipped
: When a delivery is skippedsubscriptionRenewed
: When a subscription renews successfully
Billing Events
billingAttemptFailed
: When a billing attempt failssubscriptionWillRenew
: Billing reminder notificationcardWillExpire
: When a customer's card is approaching expiration
Product/Line Item Events
subscriptionLinesAdded
: When products are added to a subscriptionsubscriptionLinesRemoved
: When products are removed from a subscriptionsubscriptionLinesUpdated
: When subscription products are updatedsubscriptionOutOfStock
: When subscription products are out of stock
Other Events
prepaidGiftReceived
: When a prepaid gift subscription is receivedsubscriptionNextBillingDateUpdated
: When the next billing date changes
4. Event Properties
Each event type includes specific properties. Here are some examples:
Subscription Cancelled Event
{
"eventName": "subscriptionCancelled",
"properties": {
"subscriptionId": "sub_123",
"email": "[email protected]",
"status": "cancelled",
"cancelledAt": "2024-03-20T10:00:00Z",
"cancellationReason": "Root reason",
"finalCancellationReason": "Specific reason"
}
}
Billing Attempt Failed Event
{
"eventName": "billingAttemptFailed",
"properties": {
"subscriptionId": "sub_123",
"email": "[email protected]",
"errorCode": "card_declined",
"errorMessage": "Card was declined",
"numberOfFailedAttempts": 1
}
}
The payload will include the following data (see Klaviyo Integration under "Sent with every data event" for details).
5. Security
Each webhook request includes a signature header (
X-Skio-Signature
) for verificationUse your webhook secret (provided during setup) to validate incoming requests
Always validate the signature before processing webhooks
6. Best Practices
Implement Idempotency: Events may be sent multiple times for reliability. Use the event ID to prevent duplicate processing.
Quick Response: Your endpoint should respond quickly (preferably under 5 seconds) to prevent timeouts.
Error Handling: Implement proper error handling and logging for failed webhook processing.
Queue Processing: Consider processing webhooks asynchronously if you need to perform time-consuming operations.
7. Testing
Use the "Send test" feature in the dashboard to test your webhook endpoint
Test your signature validation logic with the provided test events
Verify that your endpoint can handle all event types you've subscribed to
8. Rate Limiting and Reliability
Events are sent with a concurrency limit to prevent overwhelming your servers
Failed deliveries will be retried with exponential backoff
Consider implementing rate limiting on your endpoint if needed
Support
If you encounter any issues or need assistance:
Check your webhook endpoint logs
Verify your signature validation implementation
Contact Skio support with specific event IDs if you need help troubleshooting/
Last updated