Triggers

To help you react to what happens to your orders, we support triggers that can be set up to execute when a milestone in a journey is reached.

Currently, webhooks and email triggers are supported. We plan to add more trigger types in the future, such as SMS or direct system integrations.

Rollout controls

Both email and webhook triggers support Sampling rate (%) and Only fire once per order.

The sampling rate is an integer from 0 to 100 and defaults to 100%. Set it to 5% to start a small rollout, or 0% to prevent automatic firing. Selection is stable for each order and configured trigger: shipment journeys with the same settings share a decision, and retries do not reroll. The percentage is an approximate share of orders, not a fixed quota.

Enable Only fire once per order to send one logical notification even when multiple shipments reach the milestone. For example, a milestone checking for two shipments can send a single split-delivery email. Delivery failures still use normal retries. This setting defaults to off. It prevents separate firings across shipment journeys; external delivery remains at least once.

Settings are captured when journey snapshots are created. Editing a trigger affects new snapshots only; existing snapshots retain their saved values. Keeping a trigger's ID preserves its sampling identity and once-per-order history. Removing and adding a trigger creates a new identity. Manual test sends bypass both controls.

Webhook delivery history

Each actual webhook attempt adds a separate internal notification to the order and its relevant shipment. The notification includes the attempt time, webhook ID, outcome, and HTTP status when available. Network errors and timeouts are recorded without an HTTP status. A failed attempt followed by a successful retry produces two events.

Notification keys prevent duplicate history entries when recording is retried. Pending notifications are repaired automatically without resending successfully delivered webhooks. Webhook attempt notifications follow normal event processing: they reevaluate milestones and count as LAST_EVENT, so a newer attempt can move a time-since-last-event threshold forward. Newly completed milestones can trigger further notifications; already completed milestones are not fired again. Disabled webhooks and manual tests do not add delivery notifications.

Webhooks

When a milestone in a journey is reached, we can send you a message with information about the reached milestone to an HTTP endpoint of your choice.

To set up a webhook, navigate to the Administration page on Scope. Here, you can create new webhooks by providing a URL and an optional authentication token.

On the journey editing page, you can then set up the trigger on individual milestones by selecting the webhook you want to use.

The webhook will be sent as a POST request with the token provided as a Bearer token in the Authorization header. The body of the request, in JSON, will contain the following data.

Email Triggers

Email triggers allow you to automatically send customized emails to your customers when specific milestones in their order journey are reached. Email triggers currently support SendGrid dynamic templates and Postmark templates.

For how to connect each provider and test template access, see the SendGrid integration documentation and the Postmark integration documentation.

Setting Up Email Triggers

1. Create a template in SendGrid or Postmark with your desired email design
2. Configure the email trigger in your journey milestone settings
3. Map the template ID to the appropriate language(s) for localization

Template Data

When an email trigger fires, Skrym sends a JSON payload to your configured provider template. The sections below are the source of truth for the available template data.

trigger

The milestone trigger data containing information about the triggering event:

order

Complete order tracking information including shipments, events, and locations. This follows the same structure as the GetAllTrackingInfoForOrder response, with top-level keys:

• order
• origin
• destination
• references
• shipments
• events

locale

The locale Skrym resolved for this recipient. This is determined by:

1. order.order.recipientLocalePreference, if set
2. order.destination.country, if available
3. order.order.destinationCountryCode, if available
4. English (fallback)

formattedData

Preformatted, template-friendly data for the order and its shipments. This includes cleaned order references, transport details, tracking details, and locale-formatted dates.

Top-level structure:

• formattedData.order
• formattedData.shipments

The order object includes:

• orderReferences: all non-UUID order references
• transporterName
• transportMethodName
• deliveryType
• dates

Each shipment in formattedData.shipments includes:

• shipmentId
• transporterName
• transportMethodName
• deliveryType
• trackingReference
• externalReference
• trackingUrl, when available
• dates

The nested dates objects contain locale-formatted values with multiple representations:

All formatted dates are localized to the resolved locale. The example above shows Swedish output.

Example Payload

This is a trimmed real-world example of the payload Skrym sends to SendGrid templates. Some IDs and personal details have been shortened or anonymized for readability.

Template Selection and Localization

When configuring an email trigger, you map provider template IDs to one or more languages. Skrym first looks for an exact match for the resolved locale. If none is configured, it falls back to the default template. When the trigger fires, Skrym chooses the language in this order:

1. The recipient's explicit locale preference, if set
2. The destination location country, if available
3. The tracked order destination country code, if available
4. English

If you expect multiple recipient languages, configure both localized template IDs and a sensible default fallback.

Example Template Usage

In your SendGrid template, you can reference this data using Handlebars syntax:

You can access different parts of each date:

• {{formattedData.order.dates.orderCreatedAt.complete}} - Full date and time
• {{formattedData.order.dates.orderCreatedAt.dateOnly}} - Date without time
• {{formattedData.order.dates.orderCreatedAt.timeOnly}} - Just the time
• {{formattedData.order.dates.orderCreatedAt.dayNumber}} - Day number
• {{formattedData.order.dates.orderCreatedAt.monthName}} - Month name

The formatted dates automatically adapt to the recipient's language, showing localized weekday and month names.