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

1. Navigate to your Skio dashboard

2. Go to the Integrations section

3. Select your brand as your integration type

4. Provide your webhook URL where you want to receive the events

5. 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 created

• subscriptionCancelled: When a subscription is cancelled

• subscriptionReactivated: When a cancelled subscription is reactivated

• subscriptionPaused: When a subscription is paused

• subscriptionUnpaused: When a subscription is unpaused

• subscriptionSkipped: When a delivery is skipped

• subscriptionRenewed: When a subscription renews successfully

Billing Events

• billingAttemptFailed: When a billing attempt fails

• subscriptionWillRenew: Billing reminder notification

• cardWillExpire: When a customer's card is approaching expiration

Product/Line Item Events

• subscriptionLinesAdded: When products are added to a subscription

• subscriptionLinesRemoved: When products are removed from a subscription

• subscriptionLinesUpdated: When subscription products are updated

• subscriptionOutOfStock: When subscription products are out of stock

Other Events

• prepaidGiftReceived: When a prepaid gift subscription is received

• subscriptionNextBillingDateUpdated: 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": "[e-mail]",
    "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": "[e-mail]",
    "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 verification

• Use your webhook secret (provided during setup) to validate incoming requests

• Always validate the signature before processing webhooks

6. Best Practices

1. Implement Idempotency: Events may be sent multiple times for reliability. Use the event ID to prevent duplicate processing.

2. Quick Response: Your endpoint should respond quickly (preferably under 5 seconds) to prevent timeouts.

3. Error Handling: Implement proper error handling and logging for failed webhook processing.

4. Queue Processing: Consider processing webhooks asynchronously if you need to perform time-consuming operations.

7. Testing

1. Use the "Send test" feature in the dashboard to test your webhook endpoint

2. Test your signature validation logic with the provided test events

3. 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:

1. Check your webhook endpoint logs

2. Verify your signature validation implementation

3. Contact Skio support with specific event IDs if you need help troubleshooting/