Custom webhook integration for Email/SMS Platforms

Before you start

• The integration card doesn't appear by default. Contact the Skio team at help@skio.com with your store name and they'll enable it for you.

• You'll need an endpoint that can accept a POST request and validate a signature header.

• Have your webhook secret handling in place before you go live — every event is sent with a signature you're expected to verify.

What is the Custom webhook integration?

The Custom Webhook Integration sends real-time subscription events from Skio to an endpoint you control. It follows the same event model as Skio's Klaviyo integration, but instead of pushing events into an ESP, it posts them directly to your own URL — useful for custom email/SMS platforms, data warehouses, or internal automation (e.g. Workato, Zapier, or a service you built).

Set up the integration

The integration card doesn't appear by default. Contact the Skio team at help@skio.com with your store name and they'll enable it for you.

Step 1: Enable the integration

Go to Skio Dashboard > API & Integrations > Integrations. Scroll down to the Custom Webhook Integration card and toggle it on.

Step 2: Configure the webhook

Click Manage on the card to open the configuration panel, then set:

• Webhook URL: the endpoint that will receive the POST requests.

• Webhook token: auto-generated on setup. Use this to verify the X-Skio-Signature header on incoming requests. Click the eye icon to reveal it.

• Sync customer profiles: when enabled, Skio sends the full customer profile alongside every triggered event so your endpoint stays in sync without a separate lookup.

Click Save.

Step 3: Select events and test

1. Under Events, click Add events and select which triggers should fire to your endpoint.

2. Use Send test next to any configured event to fire a sample payload at your endpoint before relying on live traffic.

3. Use View event payloads to see the exact shape of each event type.

If Sync customer profiles is enabled, you can also use Backfill to push all existing customers to your endpoint, regardless of whether they've triggered an event yet.

Payload structure

Every event is a POST request with this shape:

type WebhookPayload = {
  eventName: string;          // The type of event (see below)
  eventTriggerSettings?: {    // Optional, trigger-specific
    daysBefore?: number;      // e.g. billing reminders
  };
  vendor: string;             // Integration vendor identifier
  properties: {
    email: string;
    subscriptionId?: string;
    status?: string;
    // ...additional fields depend on eventName
  };
  domain: string;             // Your shop's domain
}

Example payloads

subscriptionCancelled:

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

billingAttemptFailed:

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

Every request includes an X-Skio-Signature header. Validate it against your webhook token before processing the payload.

Available events

See all available events here.

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.

Testing

• Use Send test in the dashboard to fire a sample payload at your endpoint.

• Test your signature validation logic specifically — don't assume it works just because the test event was received. Confirm it correctly rejects a tampered or missing signature too.

• Verify your endpoint handles every event type you've subscribed to, not just the ones you tested first.

Rate limiting and reliability

• Events are sent with a concurrency limit on Skio's side to avoid overwhelming your endpoint.

• Failed deliveries are retried automatically with exponential backoff.

• If your endpoint has its own rate limits, account for retry traffic when setting them.

Troubleshooting and support

If an event doesn't show up as expected:

1. Check your endpoint's logs to confirm the request arrived.

2. Verify your signature validation logic is passing against the current X-Skio-Signature header.

3. Contact Skio support at help@skio.com with the specific event ID(s) if you need help tracing a delivery.