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

# Webhook use cases

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

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

```http theme={null}
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:

> [accordion] contact.acceptsEmail.changed
>
> Triggered whenever the `acceptsEmail` preference changes

> [accordion] contact.acceptsSms.changed
>
> Triggered whenever the `acceptsSms` preference changes

> [accordion] contact.acceptsPostal.changed
>
> Triggered whenever the `acceptsPostal` preference changes

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

> [accordion] contact.consent.changed
>
> Triggered whenever a consent value for a contact is changed
>
> ```json Payload structure theme={null}
> {
>   "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"
> }
> ```

> [!WARNING]
>
> 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](https://developer.voyado.com/docs/webhooks/webhooks.md#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:

> [accordion] contact.created
>
> Triggered when a contact is created in Customer Engagement.
>
> ```json Payload structure theme={null}
> {
>   "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"
> }
> ```

> [accordion] contact.updated
>
> Triggered when a contact is updated in Customer Engagement.
>
> ```json Payload structure theme={null}
> {
>   "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"
> }
> ```

> [accordion] contact.deleted
>
> Triggered when a contact is deleted in Customer Engagement.
>
> ```json Payload structure theme={null}
> {
>   "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.

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

> [accordion] 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.
>
> > [!WARNING]
> >
> > This is *only* for customers using the point follower solution.
>
> ```json Payload structure theme={null}
> {
>   "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
> }
> ```

> [accordion] point.balance.updated
>
> Triggered whenever a contact's point balance is changed.
>
> ```json Payload structure theme={null}
> {
>   "eventType": String,
>   "id": String,
>   "isEncrypted": Boolean,
>   "payload": : {
>     "balance": Decimal,
>     "contactId": String,
>     "accountId": Int,
>     "definitionId": String,
>     "balanceExpires": DateTimeOffset
>   },
>   "tenant": String
> }
> ```

> [accordion] reward.voucher.created
>
> Triggered when a new reward voucher is created for a contact.
>
> ```json Payload structure theme={null}
> {
>   "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
> }
> ```
>
> > [!WARNING]
> >
> > 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.

> [accordion] 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.
>
> > [!TIP]
> >
> > The event is intended to be triggered regardless of where the assignment originated: via the UI, an automation activity, or over the API.
>
> ```json Payload example theme={null}
> {
>   "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"
> }
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.