Skip to main content

Webhooks

Zuora

Webhooks

  1. Last updated
  2. Save as PDF

Within Zephr you have the ability to use Webhooks, which send third-party applications real-time information. Webhooks allow you to integrate with products that do not have a Zephr plugin. Webhooks are commonly used within Zephr to add a user to a mailing list, note in a CRM when a User hits a Paywall, or trigger automated marketing email

Adding a Webhook in Zephr is easy. You will need to know when you want to trigger the Webhook, as well as the Target End Point URL, which is where the information held within the Webhook should be sent.

To begin, navigate to Settings > Webhooks within the Zephr Admin Console, then click Add Webhook.

Complete the following fields:

  • Label – This is your webhook name
  • Triggers – This is a dropdown which reveals a full list of system triggers available to you. You can choose as many system events as you need. Supported triggers (details further below) include:
    •  User:
      • Create
      • Delete
      • Update
      • Updates Email
      • Update extended profile
      • Delete extended profile
      • Create session (includes anonymous)
      • Concurrent sessions breach
      • Login
      • Verifies Email
    • Data Retention:
      • Inactivity delete
    • Entitlement:
      • Grant
      • Grant started
      • Grant ended
    • Decision:
      • Access
    • Feature:
      • Transform
      • Custom
  • Method – Select Get, Post, Put or Delete.
  • Target – Enter the Endpoint Target URL for the system you are integrating with. For more information, check the help desk of the system you’re integrating with to find out how to listen for Webhooks.

Once the fields are complete, click Add Webhook.

Once added, the Webhooks you create will fire whenever the trigger criteria you have set is met within Zephr. If you would like to trigger a webhook in a specific part of a Zephr Rule, choose Feature – Custom as the trigger. Once the Webhook has been created and saved, follow our guide for adding a Webhook to a Feature Rule to learn how to trigger it.

Keep reading for more information on the different Webhook triggers and their 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 changes their email, 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_EMAIL",
    "time": 1603992313360,
    "details": {
        "previous_identifiers": {
            "email_address": "old@test.com"
        },
        "identifiers": {
            "email_address": "new@test.com"
        },
        "tracking_id": "fd7f9e1b-5797-470c-aec9-2e5430a85d8b"
        },
    "webhook": "Test webhook"
}

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 – Concurrent Sessions Breach

The “User Concurrent Sessions 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>"
}

Data Retention – Inactivity Delete

The “Users deleted due to inactivity” event fires periodically and reports all users that have been deleted from the system due to inactivity since their last session.

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

{
    "type": "users.inactivity.deletion",
    "time": "2012341542354", // long - milliseconds since epoc
    "details": [
        {
            "user_id": "b23402bc4-fc8f8c99-9034298423482",
            "identifiers": {
                "email_address": "x@y.co"
            },
            "attributes": {
                "foo": "bar" // based upon configured user schema
            }
            "email_verified": true,
            "last_login": "yyyy-MM-dd HH:mm:ss"
        }
    ]
}

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 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": "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>"
}

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>"
}

Feature – Transform

The Feature Transform webhook fires when the is a transformation made on a particular feature, such as showing a registration form over an article. It provides all information available pertaining to the decision that has been made.

{
  "tenantId": "tenantId",
  "subTenantId": "subTenantId",
  "type": "FEATURE_TRANSFORM",
  "time": 1597152228269,
  "details": {
    "feature": "sidebar-1",
    "entitlement-results": {},
    "context": {
      "blaize": {
        "request": {
          "country": "GB",
          "headers": {
            "Referer": "https://test.cdn.dev.zephr.com/"
          },
          "os": "Mac OSX",
          "city": "Islington",
          "crawler_verified": false,
          "device_type": "pc",
          "params": {},
          "zip_code": "N1",
          "userTimeZone": "Europe/London",
          "path": "/magazine/",
          "site": {},
          "browser": "Chrome",
          "state": "Islington",
          "siteGroup": {}
        },
        "contentApi": {},
        "session": {
          "authenticated": false,
          "testGroups": {}
        },
        "jwt": {},
        "trialChallenge": {
          "claimGift": false,
          "accessDecisionsResponse": null,
          "newOrUpdatedCrossDeviceSession": null
        },
        "customData": {},
        "featureChallenge": {
          "accessModel": {
            "meters": {},
            "credits": {},
            "delivered_entitlements": [],
            "granted_bundles": [],
            "jwt_bundles": []
          },
          "claimGift": false,
          "accessDecisionsResponse": null,
          "newOrUpdatedCrossDeviceSession": null
        },
        "customInputs": {},
        "accessModel": {
          "grantedBundles": [],
          "meterRemaining": {},
          "meterTotal": {},
          "meterConsumed": {},
          "remainingInCredit": {},
          "remainingInMeter": {},
          "creditRemaining": {},
          "creditChangedThisRequest": {},
          "meterChangedThisRequest": {}
        },
        "transform": {
          "outcomeTracker": {},
          "truncateWithStyle": {},
          "paymentForm": {},
          "resource": {},
          "setJson": {},
          "concat": {},
          "truncateString": {},
          "hostedJSONDocument": {},
          "url": {},
          "setNumber": {},
          "form": {},
          "truncate": {},
          "leavePristine": {},
          "concatJson": {},
          "formHtml": {},
          "formJson": {},
          "componentTemplate": {},
          "truncateArray": {},
          "truncateArrayAndReturnOnlyArray": {},
          "setBoolean": {}
        },
        "page": {
          "metaTagsMultiMap": {
            "datePublished": [
              "unknown"
            ],
            "viewport": [
              "width=device-width, initial-scale=1"
            ],
            "author": [
              "unknown"
            ],
            "name": [
              "Zephr Magazine"
            ],
            "description": [
              "Just another Your SUPER-powered WP Engine Multisite site"
            ],
            "url": [
              "https://wp.zephrnews.com/magazine/"
            ]
          },
          "metatags": {
            "datePublished": "unknown",
            "viewport": "width=device-width, initial-scale=1",
            "author": "unknown",
            "name": "Zephr Magazine",
            "description": "Just another Your SUPER-powered WP Engine Multisite site",
            "url": "https://wp.zephrnews.com/magazine/"
          }
        },
        "secondPartyUserData": {},
        "user": {
          "sessionState": "anonymous",
          "hasProduct": {}
        },
        "actions": {
          "firePluginHook": {},
          "fireWebhook": {}
        }
      },
      "uiComponentScope": {},
      "time": {
        "toEpoch": {},
        "secondsSinceMidnightInZone": {},
        "secondsSinceMidnight": {},
        "convertDatetimeToAgeInHours": {}
      }
    },
    "transformation": "leave_pristine"
  },
  "webhook": "test"
}

Feature – Custom

The “Feature Custom” event fires based upon a user meeting the Webhook trigger within a Zephr decision or user journey.

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

{
    "tenantId":"<tenantId>",
    "subTenantId":"training2",
    "type":"FEATURE_CUSTOM",
    "time":1552319457130,   // long - milliseconds since epoc
    "details":{
        "user_id":"31f2c40b-b28f-429f-ae10-dc1433f07c75",
        "authenticated":false,
        "access_model":{
            "meters":{
            },
            "credits":{
            },
            "delivered_entitlements":[
            ],
            "granted_bundles":[
            ]
            },
            "content_uri":"http://cdn.training2.blaize.io/sport/winter-paralympics-britons-menna-fitzpatrick-jen-kehoe-win-slalom-gold/",
            "feature_name":"article"
        },
        "webhook":"Stuff"
}