# Custom Webhook Integration for Email/SMS Platforms

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

<figure><img src="https://3129594098-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6tgHoTWVJ8jGZz1VwcUl%2Fuploads%2FaQwhyVffbZBArd4IOCY9%2FCleanShot%202025-06-03%20at%2013.48.27%402x.png?alt=media&#x26;token=4e9316e2-bc96-4cb9-8dc3-4af5736963c2" alt=""><figcaption></figcaption></figure>

#### 2. Event Payload Structure

Each webhook event will be sent as a POST request to your endpoint with the following structure:

```tsx
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

```tsx
{
  "eventName": "subscriptionCancelled",
  "properties": {
    "subscriptionId": "sub_123",
    "email": "customer@example.com",
    "status": "cancelled",
    "cancelledAt": "2024-03-20T10:00:00Z",
    "cancellationReason": "Root reason",
    "finalCancellationReason": "Specific reason"
  }
}

```

#### Billing Attempt Failed Event

```tsx
{
  "eventName": "billingAttemptFailed",
  "properties": {
    "subscriptionId": "sub_123",
    "email": "customer@example.com",
    "errorCode": "card_declined",
    "errorMessage": "Card was declined",
    "numberOfFailedAttempts": 1
  }
}

```

The payload will include the following data (see [Klaviyo Integration](https://help.skio.com/hc/en-us/articles/16802652263323-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/