Triggers

Subscribe to journey updates

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.

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.

models

MilestoneTriggerData

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

For how to connect SendGrid, create the required API key, and test template access, see the SendGrid integration documentation.

Setting Up Email Triggers

Create a dynamic template in SendGrid with your desired email design
Configure the email trigger in your journey milestone settings
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 SendGrid dynamic 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:

models

MilestoneTriggerData

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:

order.order.recipientLocalePreference, if set
order.destination.country, if available
order.order.destinationCountryCode, if available
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:

{
  "order": {
    "orderReferences": [
      "skrym-order-10"
    ],
    "transporterName": "DB Schenker",
    "transportMethodName": "Parcel",
    "deliveryType": "BUSINESS_DELIVERY",
    "dates": {
      "orderCreatedAt": {
        "complete": "torsdag, 30 april 2026, 16:24",
        "dateOnly": "torsdag, 30 april 2026",
        "timeOnly": "16:24",
        "dayNumber": "30",
        "monthName": "april"
      },
      "orderPromisedDeliveryTimeStart": {
        "complete": "lördag, 2 maj 2026, 23:00"
      },
      "orderPromisedDeliveryTimeEnd": {
        "complete": "måndag, 4 maj 2026, 23:00"
      }
    }
  },
  "shipments": [
    {
      "shipmentId": "86a436f8-cb94-4dea-b0d0-1bbbaaab30b9",
      "transporterName": "DB Schenker",
      "transportMethodName": "Parcel",
      "deliveryType": "BUSINESS_DELIVERY",
      "trackingReference": "SE88241124124",
      "externalReference": "skrym-shipment-10",
      "trackingUrl": "https://www.dbschenker.com/app/tracking-public/?refNumber=SE88241124124",
      "dates": {
        "createdAt": {
          "complete": "torsdag, 30 april 2026, 16:24"
        },
        "expectedDeliveryTimeStart": {
          "complete": "söndag, 3 maj 2026, 23:00"
        },
        "expectedDeliveryTimeEnd": {
          "complete": "måndag, 4 maj 2026, 23:00"
        },
        "completedMilestones": {
          "packed": {
            "complete": "torsdag, 30 april 2026, 16:24"
          },
          "received": {
            "complete": "torsdag, 30 april 2026, 16:24"
          }
        }
      }
    }
  ]
}

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.

{
  "formattedData": {
    "order": {
      "orderReferences": [
        "skrym-order-10"
      ],
      "transporterName": "DB Schenker",
      "transportMethodName": "Parcel",
      "deliveryType": "BUSINESS_DELIVERY",
      "dates": {
        "orderCreatedAt": {
          "complete": "torsdag, 30 april 2026, 16:24",
          "dateOnly": "torsdag, 30 april 2026",
          "timeOnly": "16:24",
          "dayNumber": "30",
          "monthName": "april"
        },
        "orderPromisedDeliveryTimeStart": {
          "complete": "lördag, 2 maj 2026, 23:00"
        },
        "orderPromisedDeliveryTimeEnd": {
          "complete": "måndag, 4 maj 2026, 23:00"
        }
      }
    },
    "shipments": [
      {
        "shipmentId": "86a436f8-cb94-4dea-b0d0-1bbbaaab30b9",
        "transporterName": "DB Schenker",
        "transportMethodName": "Parcel",
        "deliveryType": "BUSINESS_DELIVERY",
        "trackingReference": "SE88241124124",
        "externalReference": "skrym-shipment-10",
        "trackingUrl": "https://www.dbschenker.com/app/tracking-public/?refNumber=SE88241124124",
        "dates": {
          "createdAt": {
            "complete": "torsdag, 30 april 2026, 16:24"
          },
          "expectedDeliveryTimeStart": {
            "complete": "söndag, 3 maj 2026, 23:00"
          },
          "expectedDeliveryTimeEnd": {
            "complete": "måndag, 4 maj 2026, 23:00"
          },
          "completedMilestones": {
            "packed": {
              "complete": "torsdag, 30 april 2026, 16:24"
            },
            "received": {
              "complete": "torsdag, 30 april 2026, 16:24"
            }
          }
        }
      }
    ]
  },
  "locale": "sv",
  "order": {
    "order": {
      "id": "5ed82693-6dd9-4f09-a8b9-8dc42bbcfe43",
      "organizationId": "f01dab1e-babe-40dd-b1ed-ba5eba11cafe",
      "promisedDeliveryTimeStart": "2026-05-02T23:00:00Z",
      "promisedDeliveryTimeEnd": "2026-05-04T23:00:00Z",
      "originCountryCode": "SE",
      "destinationCountryCode": "SE",
      "selectedTransportMethodId": "11a3228f-313d-44fa-b3f9-86075a185003",
      "recipientName": "Skrym Customer",
      "recipientEmail": "hello@skrym.com",
      "recipientLocalePreference": "sv",
      "createdAt": "2026-04-30T16:24:09.103966Z",
      "updatedAt": "2026-04-30T16:24:24.185062Z"
    },
    "origin": {
      "city": "Stockholm",
      "zipCode": "11428",
      "address": "Drottning Kristinas Väg 53",
      "country": "SE"
    },
    "destination": null,
    "references": [
      {
        "reference": "skrym-order-10"
      }
    ],
    "shipments": [
      {
        "shipment": {
          "id": "86a436f8-cb94-4dea-b0d0-1bbbaaab30b9",
          "transporterId": "6a92c0e6-dca9-4170-a518-7bea880400b6",
          "transportMethodId": "11a3228f-313d-44fa-b3f9-86075a185003",
          "trackingMethod": "api-polling",
          "trackingReference": "SE88241124124",
          "externalReference": "skrym-shipment-10",
          "createdAt": "2026-04-30T16:24:29.117446Z",
          "expectedDeliveryTimeStart": "2026-05-03T23:00:00Z",
          "expectedDeliveryTimeEnd": "2026-05-04T23:00:00Z",
          "status": "OK"
        },
        "parcels": [],
        "events": [
          {
            "data": {
              "type": "booked"
            },
            "createdAt": "2026-04-30T16:24:29.182429Z",
            "shipmentTrackingReference": "SE88241124124",
            "trackedOrderId": "5ed82693-6dd9-4f09-a8b9-8dc42bbcfe43",
            "message": {
              "language": "en",
              "message": "Shipment added to order"
            }
          }
        ],
        "snapshots": [
          {
            "reference": "default-order-journey-v2",
            "completed": false,
            "milestones": [
              {
                "reference": "packed",
                "completed": true,
                "timeOfCompletion": "2026-04-30T16:24:29.182429Z"
              },
              {
                "reference": "received",
                "completed": true,
                "timeOfCompletion": "2026-04-30T16:24:11.408002Z"
              }
            ]
          }
        ],
        "promisedDeliveryTimeStart": "2026-05-02T23:00:00Z",
        "promisedDeliveryTimeEnd": "2026-05-04T23:00:00Z"
      }
    ],
    "events": [
      {
        "data": {
          "type": "notification"
        },
        "createdAt": "2026-04-30T16:24:11.408002Z",
        "trackedOrderId": "5ed82693-6dd9-4f09-a8b9-8dc42bbcfe43",
        "message": {
          "language": "en",
          "message": "Order created"
        }
      }
    ]
  },
  "trigger": {
    "triggerId": "eaec8e0b-e9b6-4ab4-9feb-44961066a423",
    "journeyId": "f5b7ffe7-3876-4188-85fc-1c75bce9035c",
    "milestoneId": "fd54a0a5-fc02-48ae-853f-3c5cc880dd51",
    "triggerType": "EMAIL",
    "milestoneReference": "packed",
    "milestoneSnapshotId": "e882fbf0-87a3-4a37-9da2-611bff18fcbd",
    "journeyReference": "default-order-journey-v2",
    "timestamp": "2026-04-30T16:24:30.830771278Z",
    "trackedOrderShipmentId": "cd5cfd13-0d1b-4fd5-9b4c-044fb9fdf8d0",
    "organizationId": "f01dab1e-babe-40dd-b1ed-ba5eba11cafe",
    "triggerSnapshotId": "1f53c2a8-cc23-4bc8-94e9-757fa652d0ec",
    "trackedOrderId": "5ed82693-6dd9-4f09-a8b9-8dc42bbcfe43",
    "trackedOrderReferences": [
      "skrym-order-10"
    ],
    "trackingLink": "https://www.dbschenker.com/app/tracking-public/?refNumber=SE88241124124"
  }
}

Template Selection and Localization

When configuring an email trigger, you map SendGrid 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:

The recipient's explicit locale preference, if set
The destination location country, if available
The tracked order destination country code, if available
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:

Hello!

{{#with order.order}}
  Your order was placed on {{../formattedData.order.dates.orderCreatedAt.complete}}.

  {{#if ../formattedData.order.transportMethodName}}
    Shipping method: {{../formattedData.order.transporterName}} - {{../formattedData.order.transportMethodName}}
  {{/if}}

  {{#if ../formattedData.order.dates.orderPromisedDeliveryTimeEnd}}
    Expected delivery: {{../formattedData.order.dates.orderPromisedDeliveryTimeEnd.dateOnly}}
  {{/if}}
{{/with}}

{{#each formattedData.shipments}}
  {{#if this.trackingReference}}
    Tracking reference: {{this.trackingReference}}
  {{/if}}

  {{#if this.trackingUrl}}
    Track shipment: {{this.trackingUrl}}
  {{/if}}
{{/each}}

{{#each formattedData.shipments}}
  {{#if dates.completedMilestones.PICKED_UP}}
    Package picked up on {{dates.completedMilestones.PICKED_UP.dateOnly}} at {{dates.completedMilestones.PICKED_UP.timeOnly}}
  {{/if}}

  {{#if dates.completedMilestones.IN_TRANSIT}}
    In transit since {{dates.completedMilestones.IN_TRANSIT.monthName}} {{dates.completedMilestones.IN_TRANSIT.dayNumber}}
  {{/if}}
{{/each}}

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.