Webhook use cases

Here are some examples of working with webhooks in Customer Engagement.

A complete list of events and latest payload specification can be found in the client’s Svix portal.

1 - Contact preferences & consents

Preferences are a contact’s communication channel opt-ins — the acceptsEmail, acceptsPostal, and acceptsSms boolean flags that define how a contact wants to be contacted. Consents are formal agreements a contact makes regarding their data or account (e.g., “Do you agree to receive our newsletter?” or membership terms). Once set, a consent can never revert to “Not set.” The contact preferences in use in Customer Engagement are:

acceptsEmail
acceptsSms
acceptsPostal

Other data regarding a contacts legal settings can be encoded as consent values in Customer Engagement. These are handled for every contact as custom fields on a per brand/client level. To get all consents for your Customer Engagement environment use the following endpoint:

GET /api/v3/consents

As a retailer, you will often need to show the preferences, and sometimes the consent values, for a contact. For example on My Pages or at the checkout. And you will need to be sure the values shown are correct. Since Customer Engagement often is the master of these settings, the preferences and consents will either have to be fetched every time they are needed, or you’ll need some system in place to constantly poll Customer Engagement for the current values. Neither way is efficient. This is why webhooks are a good solution.

Webhook solution

For this situation, you create a webhook for the systems you want to keep updated about contact preference changes to your contacts in Customer Engagement. Then, whenever a preference is changed in Customer Engagement, the webhook will be used to inform all the subscribed external systems, keeping them all in sync with Customer Engagement. The webhooks available for syncing of contact preferences are:

contact.acceptsEmail.changed

Triggered whenever the acceptsEmail preference changes

contact.acceptsSms.changed

Triggered whenever the acceptsSms preference changes

contact.acceptsPostal.changed

Triggered whenever the acceptsPostal preference changes

Customer Engagement also supports a dedicated webhook for changes in consent-typed fields:

Triggered whenever a consent value for a contact is changed

Payload structure

{
  "eventId": "ac01d383-b83f-45b1-a60b-275bc7bba6b2",
  "eventType": "contact.consent.changed",
  "isEncrypted": false,
  "payload": {
    "consentAlias": "myConsentAlias",
    "consentValue": true,
    "contactId": "e5f70fe1-a0cf-4d16-898e-b3d800ff4103",
    "dateChanged": "2026-01-20T16:28:38.985631+01:00"
  },
  "tenant": "myTenantName"
}

The webhooks for contact preferences and consents are only triggered for already existing contacts. They will not be triggered when a contact is created.

Be aware of the legal requirements when working with webhooks.

2 - Contact changes

Many retailers operate several systems that need access to up-to-date customer data, such as e-commerce, POS, CRM, customer service, or data platforms. If Customer Engagement is used as the source of truth for your customer data, contact webhooks can be used to keep those systems synchronized in your system whenever this data changes. The webhooks available for changes to contact data are:

contact.created

Triggered when a contact is created in Customer Engagement.

Payload structure

{
  "eventId": "4ff4d68b-d299-4a17-81cc-e81abbf8932f",
  "eventType": "contact.created",
  "isEncrypted": true,
  "payload": {
    "careOf": "c/o John Smith",
    "city": "Stockholm",
    "contactId": "515c1b2a-7124-4bb9-826b-aedbbe5da8c4",
    "contactTypeId": "Member",
    "countryCode": "SE",
    "creationTime": "2024-03-15T10:30:15Z",
    "customAttributes": {
      "myCustomAttribute": "myCustomAttributeValue"
    },
    "dateOfBirth": "2004-02-17",
    "email": "john.doe@example.com",
    "externalId": "CRM-12345",
    "firstName": "John",
    "gender": "male",
    "language": "sv",
    "lastName": "Doe",
    "marketingGroupId": "ce62abff-aeb5-45b1-90f0-909194f33c29",
    "memberNumber": "1234567",
    "mobilePhone": "+46701234567",
    "postalCode": "11122",
    "registrationByStoreId": "560d70fe-7a47-43af-87d4-875afe4f8cc3",
    "registrationDate": "2024-03-15T10:30:00Z",
    "registrationSourceType": "API",
    "registrationSpecificSource": "newsletter-signup",
    "street": "Storgatan 1",
    "swedishFinnishPersonalIdentityNumber": "20040217-7935"
  },
  "tenant": "myTenantName"
}

contact.updated

Triggered when a contact is updated in Customer Engagement.

Payload structure

{
  "eventId": "4ff4d68b-d299-4a17-81cc-e81abbf8932f",
  "eventType": "contact.updated",
  "isEncrypted": true,
  "payload": {
    "careOf": "c/o John Smith",
    "changedValues": [
      {
        "path": "Email",
        "previousValue": "previousEmail@email.com",
        "value": "myNewEmail@email.com"
      }
    ],
    "city": "Stockholm",
    "contactId": "515c1b2a-7124-4bb9-826b-aedbbe5da8c4",
    "contactTypeId": "Member",
    "countryCode": "SE",
    "creationTime": "2024-03-15T10:30:15Z",
    "customAttributes": {
      "myCustomAttribute": "myCustomAttributeValue"
    },
    "dateOfBirth": "2004-02-17",
    "email": "john.doe@example.com",
    "externalId": "CRM-12345",
    "firstName": "John",
    "gender": "male",
    "language": "sv",
    "lastName": "Doe",
    "marketingGroupId": "ce62abff-aeb5-45b1-90f0-909194f33c29",
    "memberNumber": "1234567",
    "mobilePhone": "+46701234567",
    "postalCode": "11122",
    "registrationByStoreId": "560d70fe-7a47-43af-87d4-875afe4f8cc3",
    "registrationDate": "2024-03-15T10:30:00Z",
    "registrationSourceType": "API",
    "registrationSpecificSource": "newsletter-signup",
    "street": "Storgatan 1",
    "swedishFinnishPersonalIdentityNumber": "20040217-7935",
    "updatedViaSourceType": "API",
    "updatedWithSpecificSource": "myEcom"
  },
  "tenant": "myTenantName"
}

contact.deleted

Triggered when a contact is deleted in Customer Engagement.

Payload structure

{
  "eventId": "6a21bf40-56c1-49cf-ae6e-53b987ff2da4",
  "eventType": "contact.deleted",
  "isEncrypted": true,
  "payload": {
    "contactId": "d3bdcad4-3f90-46ce-be4c-b3d800dc7979",
    "deletionReason": "cancelled membership"
  },
  "tenant": "myTenantName"
}

A typical use case for these webhooks is to create, update, or remove customer records in downstream systems whenever the customer profile changes in Customer Engagement.

The contact.updated event includes delta tracking through changedValues, which helps the system receiving the data to understand what has changed without having to infer it from the full payload.

3 - Loyalty

There are webhooks available for syncing of points and vouchers in Customer Engagement:

loyalty.addPoints

Triggered when points are added to a contact via the Customer Engagement UI or through an automation. The transaction is sent in the webhook.

This is only for customers using the point follower solution.

Payload structure

{
  "eventType": String,
  "id": String,
  "isEncrypted": Boolean,
  "payload": : {
    "amount": Decimal,
    "contactId": String,
    "pointDefinitionId": Int,
    "source": String,
    "description": String,
    "userId": String,
    "userName": String,
    "reason": String,
    "sourceId": String,
  },
  "tenant": String
}

point.balance.updated

Triggered whenever a contact’s point balance is changed.

Payload structure

{
  "eventType": String,
  "id": String,
  "isEncrypted": Boolean,
  "payload": : {
    "balance": Decimal,
    "contactId": String,
    "accountId": Int,
    "definitionId": String,
    "balanceExpires": DateTimeOffset
  },
  "tenant": String
}

reward.voucher.created

Triggered when a new reward voucher is created for a contact.

Payload structure

{
  "eventId": String,
  "eventType": String,
  "isEncrypted": Boolean,
  "payload": {
    "id": String,
    "contactId": String,
    "validFrom": DateTimeOffset | null,
    "validTo": DateTimeOffset | null,
    "currency": String,
    "uniqueCode": String,
    "rewardVoucherPayoutId": String | null,
    "value": Decimal,
  },
  "tenant": String
}

The rewardVoucherPayoutId is the ID of the payout that the voucher was issued from. After you have migrated to the new reward voucher flow, rewardVoucherPayoutId will be populated with a value and currency and value will always reflect the group currency you have configured. If your integration relies on these values, make sure it handles them correctly.

promotion.multiChannel.assigned

In some retail setups, it is Customer Engagement that decides if a customer has been assigned a promotion, while another system is responsible for making that benefit available in checkout, e-com, or POS. This, the multichannel promotion assignment webhook, can be used to notify external systems when a promotion has been assigned, so they can create or expose the corresponding coupon or voucher. This supports event-driven orchestration across channels and helps external systems react when a promotion is assigned in Customer Engagement.

The event is intended to be triggered regardless of where the assignment originated: via the UI, an automation activity, or over the API.

Payload example

{
  "eventId": "171c62d9-1007-4453-ab0b-e5bda4ace6e2",
  "eventType": "promotion.multiChannel.assigned",
  "isEncrypted": false,
  "payload": {
    "contactId": "a0e0a130-9fd1-4180-9f2e-0d38b1c2a2e4",
    "promotionAssignmentId": "7e5866cb-441f-433e-87c7-048bf8c9e41d",
    "promotionId": "d22615d8-dd23-4b40-832b-3fbafb4f2fbf",
    "timestamp": "2026-07-15T14:06:47.301Z"
  },
  "tenant": "test-tenant"
}

BI export

Delta share

Webhooks

1 - Contact preferences & consents

Webhook solution

2 - Contact changes

3 - Loyalty

​1 - Contact preferences & consents

​Webhook solution

​2 - Contact changes

​3 - Loyalty

1 - Contact preferences & consents

Webhook solution

2 - Contact changes

3 - Loyalty