System Webhooks

Last updated
Save as PDF

When creating a Webhook in Zephr, there are two types of Webhook that you can create.

System Webhooks are triggered automatically by system events happening within Zephr.

Rule Webhooks allow you to specify at which point within a rule a Webhook is triggered.

This guide looks specifically at System Webhooks and discusses:

System Webhook Triggers
System Webhook Payloads

System Webhook Triggers

When selecting the System Webhook Type, the following triggers are available. You can choose as many system triggers as you need, by toggling them on in the configuration set up:

User

Create
Delete
Update
Update Email
Update extended profile
Delete extended profile
Create session (includes anonymous)
Create tracking id
Login
Create session breach (for concurrent sessions)
Verifies Email
Remove from Account
Add to Account

Entitlement

Grant
Grant started
Grant ended
Subscription change
Subscription cancellation

Account

Grant
Grant started
Grant ended

Decision

Access

Analytics

Rule Outcome

Keep reading for more information on the different Webhook triggers and their payloads.

System Webhook Payloads

User – Create

The “User created” event fires every time a new user is created, either through registration or directly in the Admin Console / Admin API.

Any Webhooks registered to this event will send out the following payload:

{
  "tenantId": "<tenantId>",
  "subTenantId": "<subTenantId>",
  "type": "CREATE_USER",
  "time": 1592181105400,
  "details": {
    "user_id": "ce219f64-59e2-46a5-ba5f-6dc8a0b31397",
    "identifiers": {
      "email_address": "gwen@zephr.com"
    },
    "attributes": {
      "first-name": "Gwen",
      "last-name": "Doline"
    },
    "tenantId": "<tenantId>",
    "subTenantId": "<subTenantId>",
    "email_verified": false,
    "tracking_id": "e55fc897-be62-491e-93c3-ff11f7ae6274",
    "registered": "2020-06-15T00:31:44Z",
    "registration_state": "complete"
  },
  "webhook": "<webhookLabel>"
}

User – Delete

The “User deleted” event fires every time a user is deleted, either through the “forget me” API or directly in the Admin Console / Admin API.

Any Webhooks registered to this event will send out the following payload:

{
  "tenantId": "<tenantId>",
  "subTenantId": "<subTenantId>",
  "type": "DELETE_USER",
  "time": 1592181015931,
  "details": {
    "user_id": "18a9db94-b071-4ad5-984c-b9147eb8592c",
    "identifiers": {
      "email_address": "<gwen@zephr.com>"
    },
    "attributes": {},
    "tenantId": "<tenantId>",
    "subTenantId": "<subTenantId>",
    "email_verified": false,
    "tracking_id": "517c8da0-8b2b-4236-8569-975f3f9b00b5",
    "registered": "2020-06-14T23:48:07Z",
    "registration_state": "complete"
  },
  "webhook": "<webhookLabel>"
}

User – Update

The “User updated” event fires every time a user changes their core profile, either through the Public API or directly in the Admin Console / Admin API.

Any Webhooks registered to this event will send out the following payload:

{
  "tenantId": "<tenantId>",
  "subTenantId": "<subTenantId>",
  "type": "UPDATE_USER_PROFILE",
  "time": 1592181166671,
  "details": {
    "user_id": "ce219f64-59e2-46a5-ba5f-6dc8a0b31397",
    "identifiers": {
      "email_address": "gwen@zephr.com"
    },
    "attributes": {
      "gender": "Female",
      "first-name": "Gwen",
      "last-name": "Doline"
    },
    "tenantId": "<tenantId>",
    "subTenantId": "<subTenantId>",
    "email_verified": false,
    "tracking_id": "e55fc897-be62-491e-93c3-ff11f7ae6274",
    "registered": "2020-06-15T00:31:45Z",
    "registration_state": "complete"
  },
  "webhook": "<webhookLabel>"
}

User – Update Email

The “User Update Email” event fires every time a user updates their email address.

Any Webhooks registered to this event will send out the following payload:

{
  "tenantId": "tenantId",
  "subTenantId": "subTenantId",
  "type": "UPDATE_USER_EMAIL",
  "time": 1613531371288,
  "details": {
    "previous_identifiers": {
      "email_address": "<oldeEmailAddress>"
    },
    "identifiers": {
      "email_address": "<newEmailAddress>"
    },
    "tracking_id": "7b8c3eb2-370b-41f9-883b-07d01de3f0aa"
  },
  "webhook": "<webhookLabel>"
}

User – Update Extended Profile

The “User’s extended profile updated” event fires every time a user changes one of their extended profile documents.

Any Webhooks registered to this event will send out the following payload:

{
    "tenantId":"tenantID",
    "subTenantId":"subTenantId",
    "type":"UPDATE_USER_EXTENDED_PROFILE",
    "time":1597152876607,
    "details":{
        "user_id":"3e2b1d9d-e994-4c6a-9c57-bddee6f2a770",
        "identifiers":{
            "email_address":"test@zephr.com"
        },
        "test1":"{
            "identifiers":{
                "email_address":"test@zephr.com"
            },
            "validators":{
                "password":"Test123"
            }
        }"
    },
    "webhook":"webhookLabel"
}

User – Delete Extended Profile

The “User’s extended profile deleted” event fires every time a user deletes their extended profile documents.

Any Webhooks registered to this event will send out the following payload:

{
    "tenantId":"tenantId",
    "subTenantId":"subTenantId",
    "type":"DELETE_USER_EXTENDED_PROFILE",
    "time":1597153117993,
    "details":{
        "user_id":"3e2b1d9d-e994-4c6a-9c57-bddee6f2a770",
        "identifiers":{
            "email_address":"test@zephr.com"
        },
        "test1":{
        }
    },
    "webhook":"webhookLabel"
}

User – Create Session

The “User Create Session” event fires when a session is created, including an anonymous session.

Any Webhooks registered to this event will send out the following payload:

{
  "tenantId": "<tenantId>",
  "subTenantId": "<subTenantId>",
  "type": "SESSION_CREATE",
  "time": 1592178686326,
  "details": {
    "tenantId": "<tenantId>",
    "subTenantId": "<subTenantId>",
    "supplied": false,
    "expiryDate": "2021-06-14 23:51 PM UTC",
    "startDate": "2020-06-14 23:51 PM UTC",
    "authenticated": true,
    "state": "authenticated",
    "device": "pc",
    "browser": "Chrome",
    "os": "Mac OSX",
    "city": "Dublin",
    "immutable": true,
    "session_id": "c6d00245-61ce-43e7-be93-edff8ae06906",
    "user_id": "0747c739-e758-4908-896d-d5734e0e3e09"
  },
  "webhook": "<webhookLabel>"
}

User – Login

The “User login” event fires every time a user logs in.

Any Webhooks registered to this event will send out the following payload:

{
  "tenantId": "<tenantId>",
  "subTenantId": "<subTenantId>",
  "type": "LOGIN_USER",
  "time": 1592181272022,
  "details": {
    "tenantId": "<tenantId>",
    "subTenantId": "<subTenantId>",
    "supplied": false,
    "expiryDate": "2021-06-15 00:34 AM UTC",
    "startDate": "2020-06-15 00:34 AM UTC",
    "authenticated": true,
    "state": "authenticated",
    "device": "pc",
    "browser": "Chrome",
    "os": "Mac OSX",
    "city": "Dublin",
    "immutable": true,
    "session_id": "c3382226-4db6-4259-8e2a-425518e2c3ba",
    "user_id": "8bd85938-80dc-48a7-a1d9-f42e4040b3ef"
  },
  "webhook": "<webhookLabel>"
}

User – Current Session Breach

The “User Current Session Breach” event fires when a user breaches their concurrent session limit (and thus is logged out of a previous session). Read our Restrict Account Sharing guide for more details.

Any Webhooks registered to this event will send out the following payload:

{
  "tenantId": "<tenantId>",
  "subTenantId": "<subTenantId>",
  "type": "CONCURRENT_SESSIONS_BREACH",
  "time": 1592179087683,
  "details": {
    "tenantId": "<tenantId>",
    "subTenantId": "<subTenantId>",
    "supplied": false,
    "expiryDate": "2021-06-14 23:57 PM UTC",
    "startDate": "2020-06-14 23:57 PM UTC",
    "authenticated": true,
    "state": "authenticated",
    "device": "pc",
    "browser": "Chrome",
    "os": "Mac OSX",
    "city": "Dublin",
    "immutable": true,
    "session_id": "07732a63-fcbc-4c34-8d44-54fb7bc846aa",
    "user_id": "7010a889-abf5-49ca-9141-b78ce2d540c7"
  },
  "webhook": "<webhookLabel>"
}

User – Verifies Email

This webhook is sent at the point that a User verifies their email if you require email verification upon registration within Zephr.

{
    "tenantId":"<tenantId>",
    "subTenantId":"<subTenantId>",
    "type":"VERIFY_EMAIL",
    "time":157175564639,
    "details":{
        "tenantId":"<tenantId>",
        "subTenantId":"<subTenantId>",
        "user_id":"60e15477-c22d-4905-b79a-30c14d3e27fe"
    },
    "webhook":"<webhookLabel>"
}

User – Remove From Account

This webhook is sent at the point a user is removed from a corporate account.

{
  "tenantId": "tenantId",
  "subTenantId": "subTenantId",
  "type": "ACCOUNT_USER_DELETED",
  "time": 1613532249016,
  "details": {
    "accountUser": {
      "user_id": "c48a790d-26d7-46b0-bbde-cdb0d46574b8",
      "identifiers": {
        "email_address": "<emailAddress>"
      },
      "attributes": {},
      "tenantId": "<tenantId>",
      "subTenantId": "<subTenantId",
      "email_verified": false,
      "tracking_id": "7b8c3eb2-370b-41f9-883b-07d01de3f0aa",
      "registered": "2021-02-17T02:27:54Z",
      "registration_state": "complete",
      "registration_tenant": "<registrationTenant"
    },
    "currentNumberOfUsers": 3
  },
  "webhook": "<webhookLabel>"
}

User – Add To Account

This webhook is sent at the point a user is added to a corporate account.

{
  "tenantId": "tenantId",
  "subTenantId": "subTenantId",
  "type": "ACCOUNT_USER_CREATED",
  "time": 1613532273008,
  "details": {
    "accountUser": {
      "user_id": "c48a790d-26d7-46b0-bbde-cdb0d46574b8",
      "identifiers": {
        "email_address": "<emailAddress>"
      },
      "attributes": {},
      "tenantId": "<tenantId>",
      "subTenantId": "<subTenantId>",
      "email_verified": false,
      "tracking_id": "7b8c3eb2-370b-41f9-883b-07d01de3f0aa",
      "registered": "2021-02-17T02:27:54Z",
      "registration_state": "complete",
      "registration_tenant": "<registrationTenant>"
    },
    "currentNumberOfUsers": 4
  },
  "webhook": "<webhookLabel>"
}

Entitlement – Grant

The “Entitlement granted” event fires every time an entitlement is granted to a user, either by purchasing a product or by direct grant via the Admin Console / Admin API.

Any Webhooks registered to this event will send out the following payload:

{
  "tenantId": "<tenantId>",
  "subTenantId": "<subTenantId>",
  "type": "ENTITLEMENT_GRANT",
  "time": 1592181363055,
  "details": {
    "tenantId": "<tenantId>",
    "subTenantId": "<subTenantId>",
    "grant_id": "8f3b3d92-0fc8-45db-86a3-118474908eca",
    "user_id": "ce219f64-59e2-46a5-ba5f-6dc8a0b31397",
    "expiry_state": "active",
    "entitlement_type": "entitlement",
    "entitlement_id": "1d405fbd-38ec-47a7-bb83-d185d8738550",
    "product_id": null,
    "test_groups": {}
  },
  "webhook": "<webhookLabel>"
}

Entitlement – Grant Started

The “Entitlement Grant Started” event fires when an entitlement is directly granted to a user through the Admin console and the grant moves from a Pending state to an Active state.

Any Webhooks registered to this event will send out the following payload:

{
  "tenantId": "<tenantId>",
  "subTenantId": "<subTenantId>",
  "type": "GRANT_STARTED",
  "time": 1592180693787,
  "details": {
    "tenantId": "<tenantId>",
    "subTenantId": "<subTenantId>",
    "grant_id": "f4b88efd-6573-411d-b4b8-b776a6f5ecfa",
    "user_id": "8bd85938-80dc-48a7-a1d9-f42e4040b3ef",
    "expiry_state": null,
    "entitlement_type": "entitlement",
    "entitlement_id": "1d405fbd-38ec-47a7-bb83-d185d8738550",
    "product_id": null
  },
  "webhook": "<webhookLabel>"
}

Entitlement – Grant Ended

The “Entitlement Grant Ended” event fires every time an entitlement is removed/revoked for a user, either automatically (via grant expiry) or via the Admin Console / Admin API.

Any Webhooks registered to this event will send out the following payload:

{
  "tenantId": "<tenantId>",
  "subTenantId": "<subTenantId>",
  "type": "GRANT_ENDED",
  "time": 1592180824040,
  "details": {
    "tenantId": "<tenantId>",
    "subTenantId": "<subTenantId>",
    "grant_id": "f4b88efd-6573-411d-b4b8-b776a6f5ecfa",
    "user_id": "8bd85938-80dc-48a7-a1d9-f42e4040b3ef",
    "expiry_state": "active",
    "entitlement_type": "entitlement",
    "entitlement_id": "1d405fbd-38ec-47a7-bb83-d185d8738550",
    "product_id": null
  },
  "webhook": "<webhookLabel>"
}

Entitlement – Subscription Change

The “Subscription Change” event fires every time an end user changes subscriptions in the Preference Centre.

Any Webhooks registered to this event will send out the following payload:

{
  "tenantId": "",
  "subTenantId": "",
  "type": "SUBSCRIPTION_CHANGE",
  "time": 1675419716659,
  "details": {
    "productFrom": "silver",
    "productTo": "gold",
    "planFrom": {
      "name": "test monthly plan silver",
      "price": 8,
      "frequency": {
        "interval": "MONTH",
        "intervalCount": 1
      }
    },
    "planTo": {
      "name": "test annually plan",
      "price": 90,
      "frequency": {
        "interval": "MONTH",
        "intervalCount": 1
      }
    },
    "location": {
      "city": "New Delhi",
      "country": "IN"
    },
    "userAgent": {
      "browser": "Chrome",
      "os": "Mac OS >=10.15.7",
      "deviceName": "Apple Macintosh"
    },
    "userId": "1ab1898c-9e44-4dfe-8804-714de35bcfd3",
    "trackingId": "2f904756-f490-4220-9a0a-bf8d7f92683e",
    "navigatedFrom": "Zephr Preference Center: "
  },
  "webhook": "change subscriptions"
}

Entitlement – Subscription Cancellation

The “Subscription Cancellation” event fires every time an end user cancels subscriptions.

Account – Account Grant

This webhook is triggered when granting a product to a Company Account from within the Account Details page in the Zephr Admin Console.

Any webhooks registered to this event will send out the following payload:

{
  "tenantId": "<tenantId>",
  "subTenantId": "<subTenantId>",
  "type": "ACCOUNT_GRANT",
  "time": 1616407188900,
  "details": {
    "tenantId": "<tenantId>",
    "subTenantId": "<subTenantId>",
    "grant_id": "24b16fac-35ea-4a7c-bf71-72fb50c33448",
    "account_id": "9fe3c35f-9fb8-4942-8cd9-2aec3da02a32",
    "expiry_state": "active",
    "entitlement_type": "bundle",
    "entitlement_id": "87a55834-fc97-4051-abdb-e72c41d16818",
    "product_id": null,
    "test_groups": {}
  },
  "webhook": "<webhookLabel>"
}

Account – Account Grant Started

This webhook is triggered when granting a product to a Company Account from within the Account Details page in the Zephr Admin Console, and the grant start time is not in the future.

Any webhooks registered to this event will send out the following payload:

{
  "tenantId": "<tenantId>",
  "subTenantId": "<subTenantId>",
  "type": "ACCOUNT_GRANT_STARTED",
  "time": 1616407188900,
  "details": {
    "tenantId": "<tenantId>",
    "subTenantId": "<subTenantId>",
    "grant_id": "24b16fac-35ea-4a7c-bf71-72fb50c33448",
    "account_id": "9fe3c35f-9fb8-4942-8cd9-2aec3da02a32",
    "expiry_state": "active",
    "entitlement_type": "bundle",
    "entitlement_id": "87a55834-fc97-4051-abdb-e72c41d16818",
    "product_id": null
  },
  "webhook": "<webhookLabel>"
}

Account – Account Grant Ended

This webhook is triggered when revoking a product grant for a Company Account from within the Account Details page in the Zephr Admin Console, or when a grant is marked as expired.

Any webhooks registered to this event will send out the following payload:

{
  "tenantId": "<tenantId>",
  "subTenantId": "<subTenantId>",
  "type": "ACCOUNT_GRANT_ENDED",
  "time": 1616407857582,
  "details": {
    "tenantId": "<tenantId>",
    "subTenantId": "<subTenantId>",
    "grant_id": "24b16fac-35ea-4a7c-bf71-72fb50c33448",
    "account_id": "9fe3c35f-9fb8-4942-8cd9-2aec3da02a32",
    "expiry_state": "active",
    "entitlement_type": "bundle",
    "entitlement_id": "87a55834-fc97-4051-abdb-e72c41d16818",
    "product_id": null
  },
  "webhook": "Acc Grant End"
}

Decision – Access

The “Access decision made” event fires every time there is a challenge made for access. This is usually an internal mechanism but the Webhook exposes the challenge and response in the form a mapping between required entitlements and whether or not the user was entitled to them.

Any Webhooks registered to this event will send out the following payload:

{
  "tenantId": "<tenantId>",
  "subTenantId": "<subTenantId>",
  "type": "ACCESS_DECISION",
  "time": 1592181497049,
  "details": {
    "accessDecisions": {},
    "meterChanges": {},
    "creditChanges": {},
    "newOrUpdatedCrossDeviceSession": {
      "tenantId": "<tenantId>",
      "subTenantId": "<subTenantId>",
      "authenticated": false,
      "v": 0,
      "session_variables": {},
      "user_id": "212917da-10fc-4b65-9fed-1198770c0796",
      "sessions": [],
      "access_model": {
        "meters": {},
        "credits": {},
        "delivered_entitlements": [],
        "granted_bundles": [],
        "jwt_bundles": []
      },
      "last_updated": null,
      "test_groups": {
        "registration-test": "A"
      },
      "second_party_data": {}
    },
    "updatedAccessModel": {
      "meters": {},
      "credits": {},
      "delivered_entitlements": [],
      "granted_bundles": [],
      "jwt_bundles": []
    }
  },
  "webhook": "<webhookLabel>"
}

Analytics - Rule Outcome

The Rule Outcome webhook is only for customers using Zephr Optimize's in-rule analytics. It cannot be used as a standalone webhook. Contact your CSM for more information about Zephr's analytics offering.

The "Rule outcome" event fires once per request if the request involves rule execution. If there are multiple features on a single page, only one webhook invocation will be made with the outcomes of all the rules.

Note: It might be necessary to load and resave a rule to take advantage of this webhook if the rule was last updated before 24/04/23.

Any Webhooks registered to this event will send out the following payload:

{
  "tenantId": "testtenant",
  "subTenantId": "testtenant|demo",
  "type": "RULE_OUTCOME",
  "time": 1682328910202,
  "details": {
    "userId": "aaa0124c-c665-4368-ab24-554e7fd0e6f7",
    "sessionId": "aaa0124c-c665-4368-ab24-554e7fd0e6f7",
    "trackingId": "b009cbd3-f07b-4675-9f46-d8101938b995",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:109.0) Gecko/20100101 Firefox/109.0",
    "uri": "http://jamesleach-demo.cdn.zephr.com/2013/01/01/threaded-comments/",
    "country": "IE",
    "state": "Leinster",
    "city": "Dublin",
    "outcomes": [
      {
        "ruleId": "H-article-140",
        "outcomeId": "graph/1#2,graph/1#3,graph/1#5,graph/2#1,graph/2#2,transformation/4",
        "outcomeLabel": "sf"
      }
    ]
  },
  "webhook": "rule outcome"
}