---
title: "Custom webhook integration for Email/SMS Platforms"
slug: "custom-webhook-integration"
updated: 2026-08-19T17:31:09Z
published: 2026-08-19T17:31:09Z
canonical: "help.skio.com/custom-webhook-integration"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.skio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/help/docs/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

> [!WARNING]
> 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.

![Custom Webhook Integration card in the Skio Dashboard Integrations list, showing Connected status and a Manage button](https://cdn.us.document360.io/a953bba6-c70d-43ce-bc77-d7f32a8fc514/Images/Documentation/base64-converted-image-1784647059183.png?sv=2026-02-06&spr=https&st=2026-10-28T10%3A40%3A49Z&se=2026-10-28T11%3A40%3A49Z&sr=c&sp=r&sig=ghfjbQeRqZmK7yVUJmvRwcsDdRBhSkuAd8qnlL40Sto%3D)

The Custom Webhook Integration card, found at the bottom of **API & Integrations** > **Integrations**.

### 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**.

![](https://cdn.us.document360.io/a953bba6-c70d-43ce-bc77-d7f32a8fc514/Images/Documentation/CleanShot 2026-07-22 at 17.28.51@2x.png?sv=2026-02-06&spr=https&st=2026-10-28T10%3A40%3A49Z&se=2026-10-28T11%3A40%3A49Z&sr=c&sp=r&sig=ghfjbQeRqZmK7yVUJmvRwcsDdRBhSkuAd8qnlL40Sto%3D)

Webhook configuration panel: URL, token, profile sync, backfill, and event selection.

### 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.

![Custom Webhook Integration Events tab showing the View event payloads button above the list of configured events](https://cdn.us.document360.io/a953bba6-c70d-43ce-bc77-d7f32a8fc514/Images/Documentation/base64-converted-image-1784755997835.png?sv=2026-02-06&spr=https&st=2026-10-28T10%3A40%3A49Z&se=2026-10-28T11%3A40%3A49Z&sr=c&sp=r&sig=ghfjbQeRqZmK7yVUJmvRwcsDdRBhSkuAd8qnlL40Sto%3D)

The Events tab lists every event you've added, with**Send test**and delete controls per row.**View event payloads**opens the full schema reference.

> [!NOTE]
> 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:

```plaintext
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`:

```plaintext
{
  "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`:

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

> [!WARNING]
> Every request includes an `X-Skio-Signature` header. Validate it against your webhook token before processing the payload.

## Available events and properties

> [!NOTE]
> [See all available events here.](/help/docs/all-skio-event-metrics)

> [!NOTE]
> [See all available customer profile properties here.](/help/docs/skio-properties-sent-to-klaviyo) These are the same properties sent to integrations such as [Klaviyo](/help/docs/klaviyo-integration).

## 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.

---

### FAQ

#### Can I test my webhook before going live?

Yes. Use **Send test** next to any configured event in the integration panel to fire a sample payload at your endpoint.

#### What happens if my endpoint is down?

Failed deliveries are retried with exponential backoff. Events are also sent with a concurrency limit so your server isn't overwhelmed.

#### Can I get existing customers into my endpoint, not just new events?

Yes, if **Sync customer profiles** is enabled. Use the **Backfill** button to push all existing customer profiles to your endpoint at once.