SAP Customer Data Cloud Positions


Skip to end of metadata
Go to start of metadata


Gigya webhooks offer a flexible way to extend Gigya's flows by sending out to your server a notification of a specific Gigya event that has occurred. With webhooks, you can implement your own code, and set it to trigger when the relevant hook is fired. Webhook notifications are sent in near real-time and are delivered at least once.

They may contain multiple events to improve efficiency and bandwidth utilization.

Events are ordered per UID, meaning that per UID, events are delivered in the order in which they occur.

You may configure the platform to deliver notifications for specific event types. Common use cases include:

  • Sending personalized marketing materials to a user based on particular actions.
  • Replicating your user database.

If you have an SAP logon, you can watch an instructional video about Webhooks, here.


When configuring Webhooks, you may select the version of Webhooks to use. Newer versions may cause webhook notifications to be sent that you have not received previously (e.g., a webhook notification for a lite account interaction). Therefore, before choosing a more advanced version, make sure your downstream systems are prepared to receive the new type of notifications and/or associated data.

Current supported versions: 

  • 1.0 - Webhooks will be sent out only for interactions performed by fully registered accounts. 

    This version will no longer be supported after July 5, 2021.

  • 1.1 - Webhooks will be sent out also for lite account interactions, and will include a callId and version. For more information, see Lite Webhook Notifications.

    This version will no longer be supported after July 5, 2021.

  • 2.0 - Support for using webhooks with Global Access, includes the following: 
    • Sign the webhook notifications with a JWT. For more information, see Validate A JWT from SAP Customer Data Cloud
    • Webhooks can be verified with the accounts.getJWTPublicKey endpoint without having to exchange secrets with the webhook recipient. 
    • Version 2.0 adds the API key of the site that initiated the notification to the webhook payload, supporting site group scenarios where an event should be triggered only when a webhook was initiated from a specific site.


Supported Events

The following events are supported:

  • Account created - fired when a new account record is actually created in the database. Note that when using version 1.1 or higher of Webhooks, if the account has progressed from lite to full, the account created event will not fire for a full registration, since the account has already been created .
  • Account registered - fired when a user completes registration.
  • Account updated - fired when a user record is updated.
  • Account deleted - fired when an account is deleted.
  • Account logged in - fired when a user logs in.
  • Account locked out - fired when an account is locked out, due to suspicious login attempts, as detected by Risk Based Authentication
  • Account merged - fired when accounts are linked in a link account scenario.
  • Account progressed - fired when an account progresses from lite to full. 
  • Account UID changed - fired whenever the UID changes for this account. For example, when calling socialize.setUID
  • Subscription updated - fired when the status of a subscription changes (subscribed / unsubscribed, or a change in the double opt-in status). For more information, see Subscription Management. Currently, this event does not include an accountType and callId.
  • Site preferences reset - if the preferences status were reset for this user by calling accounts.resetSitePreferences.

Subscribing to Events

Perform the following for each site in which you want to use webhooks. Note that for site groups, every site that has a webhook defined for a specific event will receive that event from any other site in the group, whether they have any webhooks defined or not. For more information see Site Group Notifications

  1. Go to the Webhooks page In Gigya's Console. You may also access it from the Settings menu, under Registration-as-a-Service
  2. Click Create Webhook
  3. In the Create Webhook page: 

    1. Enter a unique name.
    2. Enter the Notification URL in your server to which webhook notification objects will be sent when the subscribed event is fired.

      When updating the Notification URL for an existing webhook, allow some time for the new URL to update and make sure it is updated in the system, before removing the previously used URL.

    3. If you are using version 1.0 or 1.1, choose whether to sign the notifications using your partner secret key, or a user/app key, in which case you should also enter the key. If you are using version 2.0, the webhook will be signed with a JWT. For more information, see Validate A JWT from SAP Customer Data Cloud.
    4. Select the events to which this webhook is subscribed. 
    5. Enter details of HTTP custom headers, then press the plus button. For more information, see below.
    6. Click Create.


  • You may subscribe multiple Notification URLs to any combination of events. This may be useful where you want notifications for the same event sent to multiple systems to be processed independently.
  • Creating a webhook uses the accounts.webhooks.set API.

Custom Headers

You can add custom HTTP headers, made of key-value pairs, to be sent together with the webhook notification. You can use these headers to add any additional details and context to the notification, e.g. an ID or flag that is consumed by a third-party system downstream.

Note the following limitations. Limitations are case insensitive:

  • The key (name) is limited to 50 characters and the value to 100 characters.
  • You can add a maximum of 10 custom headers per webhook.

  • Header name and value should be validated according to HTTP RFC.

  • The header value can't contain ASCII 10,13, or 9 (tab, line feed, or carriage return).

  • In addition, the following are not allowed as keys or values of custom headers: 

     Click for key and value restrictions


    • "Accept"
    • "Accept-Charset"
    • "Accept-Encoding"
    • "Accept-Language"
    • "X-Gigya-Sig-HMAC-SHA1"
    • "Expect"
    • "From"
    • "Host"
    • "If-Match"
    • "If-Modified-Since"
    • "If-None-Match"
    • "If-Range"
    • "If-Unmodified-Since"
    • "Max-Forwards"
    • "Range"
    • "Referer"
    • "TE"
    • "User-Agent"
    • "Accept-Ranges"
    • "Age"
    • "ETag"
    • "Location"
    • "Retry-After"
    • "Server"
    • "Vary"
    • "Cache-Control"
    • "Connection"
    • "Date"
    • "Pragma"
    • "Trailer"
    • "Transfer-Encoding"
    • "Upgrade"
    • "Via"
    • "Warning"
    • "Cookie"
    • "Content-Type"
    • "Keep-Alive"
    • "Content-Length"
    • "Content-Encoding"
    • "Forwarded"
    • "X-Forward-For"
    • "__requestVerificationToken"

Even though the Webhooks interface is secure and uses HTTPS, we recommend that custom headers not be used for authentication or storing credentials for any other purposes.

Organization Management Webhooks

Subscribing to notifications for CIAM for B2B requires configuring webhooks in the SAP Customer Data Cloud Console, and configuring the Organization Management Console. 

  1. Create a new Webhook in the SAP Customer Data Cloud Console as described above.
  2. Select the relevant organization management notifications (e.g. 'Organization entered draft stage').
  3. Open the Organization Management module. 
  4. On the relevant partner tab, select Manage
  5. Open the Settings menu. 
  6. Select the relevant site / site group and click Details and Edit
  7. Make sure Allow External Integration is on. Select Save and click the back arrow to return to the Settings menu.

  8. Back in the Settings menu, select Approvals.

  9. Edit the approval flow and click Add Step.
  10. Select the Remote System tab and choose the configured webhook. 
  11. Specify the path name and save the configuration. 

Managing Webhooks 

In the Webhooks section of the Console, you can see a list of your defined webhooks. Open the Actions menu to edit or delete the webhook, or see their status: 

You can use the following APIs to achieve the same functionality: 

Notification Format

The notification consists of an HTTP POST request containing a Notification Object in the body. Gigya may include up to 100 multiple events in a single notification.

Notification Object Members

Field NameTypeDescription

An array of JSON objects, each one consisting of:

  • type - The event type. Possible values are:
    • accountCreated
    • accountRegistered
    • accountUpdated
    • accountDeleted
    • accountLoggedIn
    • accountLockedOut
    • accountMerged
    • accountProgressed
    • accountUidChanged
    • sitePreferencesReset
    • subscriptionUpdated
    • organizationRequested
    • organizationEnteredDraftStage
    • organizationEnteredApprovalWorkflow
    • organizationActivated
    • organizationSuspended
    • organizationRejected
    • organizationWorkflowEnabled
  • id - A unique identifier for this event.

    Since events may be sent more than once, use the id to check for duplicates. The id for a specific event will always be the same.
  • timestamp - The GMT time when the event was triggered, in UNIX time format, i.e., the number of seconds since Jan. 1st 1970.
  • data - A JSON object containing:
    • uid - The UID of the user for which the event was triggered.
    • emailAccountToken - This is only returned in a subscriptionUpdated webhook. The token needed for various lite account related operations to avoid using the user's actual email address in requests.
    • accountType - The type of the account associated with the event. Value may be "full" or "lite". Available from version 1.1 and higher.

  • callId - A unique identifier of the original call that caused this webhook event to fire. Available from version 1.1 or higher.
noncestringA random string used as part of the hash. For more information, see Notification Security.
timestampnumberThe GMT time when the notification was sent, in UNIX time format, i.e., the number of seconds since Jan. 1st 1970.

Example Notification Object A

  "events": [
      "type": "accountLoggedIn",
      "id": "af54e8a3-XXX-XXX-XXX-XXX",
      "timestamp": 1587917550,
      "callId": "0fc9XXX",
      "version": "2.0",
      "apiKey": "4_PBxxxZ-Q",
      "data": {
        "accountType": "full",
        "uid": "33cxxx797"
      "type": "accountRegistered",
      "id": "5c7464e2-XXX-XXX-XXX-XXX",
      "timestamp": 1587917550,
      "callId": "0fc9XXX",
      "version": "2.0",
      "apiKey": "4_PBxxxZ-Q",
      "data": {
        "accountType": "full",
        "uid": "33cxxx797"
  "nonce": "c77919b1-XXX-XXX-XXX-XXX",
  "timestamp": 1587917553
  "events": [
      "type": "accountCreated",
      "id": "549f3f9b-XXX-XXX-XXX-XXX",
      "timestamp": 1587917548,
      "callId": "0fc9XXX",
      "version": "2.0",
      "apiKey": "4_PBxxxZ-Q",
      "data": {
        "accountType": "full",
        "uid": "33cxxx797"
  "nonce": "9bb...-XXX-XXX-XXX-XXX",
  "timestamp": 1587917551


Example Notifications Object B

	"events": [{
		"type": "subscriptionUpdated",
		"timestamp": 1564393095,
		"data": {
			"subscription": {
				"myNewsletter": {
					"email": {
						"isSubscribed": false,
						"lastUpdatedSubscriptionState": "2019-07-29T09:38:15.9593474Z",
						"tags": null,
						"doubleOptIn": {
							"confirmTime": null,
							"emailSentTime": null,
							"status": "NotConfirmed"
	}, {
		"type": "subscriptionUpdated",
		"timestamp": 1564393095,
		"data": {
			"subscription": {
				"partnerNewsletter": {
					"email": {
						"isSubscribed": true,
						"lastUpdatedSubscriptionState": "2019-07-29T09:38:15.9593474Z",
						"tags": null,
						"doubleOptIn": {
							"confirmTime": null,
							"emailSentTime": "2019-07-29T09:38:15.9593474Z",
							"status": "Pending"
	"timestamp": 1564393105



Site Group Notifications

Notifications from any site are automatically sent to all sites, including the parent, as long as each site is subscribed to the given event type. This means that all events within the group will be sent to all the URLs of all children that are subscribed to the specific event. When using version 2.0, an API key is included in the notification, for supporting triggering different flows for different sites.

For example, given the following Site Group and configuration, if an account is created on Site B, an accountCreated notification will be sent to Sites P, A and B:

Notification Security

To ensure that a given notification originated from Gigya and that none of its data has been tampered with in transit, notifications contain a signature in the X-Gigya-Sig-Hmac-Sha1 header.

The signature is constructed by BASE64 encoding the HMAC-SHA1 hash of the JSON payload, using your Application Secret or Partner Secret as the key.

Handling Notifications

Verifying the Hash

It's important to verify the hash to ensure the authenticity of the notification. 

Version 1

The hash is passed in the X-Gigya-Sig-Hmac-Sha1 header. To verify the hash:

  1. Create an HMAC-SHA1 hash of the JSON payload using an Application Secret or Partner Secret as the key. For more information on signing notifications using an Application Secret, see the signingUserKey property of accounts.webhooks.set. For more information, see Signing Requests to SAP Customer Data Cloud.
  2. Compare your hash to the one received in the X-Gigya-Sig-Hmac-Sha1 header.

If the hashes match, the notification is considered valid.

Version 2

To verify the autיenticity of the Webhook 2.0 notification:

  1. Retrieve the JWT from the header x-gigya-sig-jwt. 
  2. Validate the JWT. For more information, see Validate A JWT from SAP Customer Data Cloud.
  3. The subject ("sub") of the JWT is a Base64URL encoding of the hash of the Webhook event body. Decode the JWT subject from Base64URL to hex. 
  4. Apply SHA256 to the Webhook event body (raw content) and compare it to the decoded JWT subject. 


Return a Valid HTTP Status Code

Gigya considers notifications delivered if a 2XX Success HTTP status code is received (e.g., 200 OK, 201 Created, 202 Accepted). Gigya will wait 10 seconds before considering the notification unsuccessful. If we receive anything other than a Success response from your server, we will resend the notification at increasing intervals up to one hour. If we receive no response at all, we assume that your callback endpoint is offline. When your callback endpoint comes back online, we will deliver notifications from the three previous hours in the prior to the endpoint being detected as being active (if they were not already delivered).

We recommend that once a notification is received, you return a 2XX Success immediately, before continuing to process it. Waiting too long to respond may cause the notification to be resent unnecessarily.

In the event that your endpoint is out of service for more than 3 hours, you may retrieve any missed webhook data manually via alternate methods as you would normally, i.e., using the API for the time frame in question.

Additionally, it is not necessary to contact Gigya to re-enable webhooks in the event of an outage, Gigya is able to detect when your server is back online and will automatically continue sending the notifications.

Gigya recommends enqueuing the webhook data after sending the 200 Success HTTP status code, and processing the data asynchronously. A queue data structure is recommended to maintain the order of event data.


Code Example

The following is a sample PHP file used as a callback url endpoint. The page receives Gigya's notification and authenticates the hash. If the hash is valid, it outputs the event type and UID to the screen and responds with a 200 OK so Gigya won't resend the notification; if it's not valid, it responds with a 400 Bad Request.

// This should be replaced with your actual Partner Secret, or if signing using a User Key, the secret for that key.
$SIGNINGKEYSECRET = "signing_key_secret";
// PHP converts the header into all UPPERCASE, converts hyphens("-") into underscores("_") and prepends "HTTP_"
// or "HTTPS_" to the front, based on the protocol used.
// Keep this in mind if converting this code to work in a language other than PHP. 
// The actual header passed by Gigya is: "X-Gigya-Sig-Hmac-Sha1".
$msgHash = $_SERVER['HTTP_X_GIGYA_SIG_HMAC_SHA1']; // How PHP sees the X-Gigya-Sig-Hmac-Sha1 header
// Get the JSON payload sent by Gigya.
$messageJSON = file_get_contents('php://input');
// Decode the JSON payload into an associative array.
$jsonDecoded = json_decode($messageJSON, TRUE);
// Builds and returns expected hash
function createMessageHash($secret, $message){
    return base64_encode(hash_hmac('sha1', $message, base64_decode($secret), true));
// Compares the two parameters (in this case the hashes) and returns TRUE if they match
// and FALSE if they don't.  
function hashesMatch($expected, $received){
    if ($expected == $received) {
        return TRUE;
    return FALSE;
// Check if the hash matches. If it doesn't, it could mean that the data was tampered
// with in flight. If so, do not send 2XX SUCCESS - let Gigya re-send the notification.
if (hashesMatch(createMessageHash($SIGNINGKEYSECRET, $messageJSON), $msgHash)) {
    // Loop through the events portion of the notification.
    for ($x=0; $x<sizeof($jsonDecoded['events']); $x++ ){
    $curEvt = $jsonDecoded['events'][$x]['type'];
    $curUID = $jsonDecoded['events'][$x]['data']['uid'];
    ** This is where we would normally do something with this info.
    ** For the sake of this example though, we'll just output
    ** the info to the screen.
    echo "Event Type: $curEvt \n";
    echo "UID: $curUID \n\n";
    // Since the hash is good and we've done what we need to do, respond OK. Gigya will not resend this notification.
} else {
    // The hash isn't good, respond non-OK. Gigya will try to resend this notification at progressively longer intervals.



API Event Mapping

The following table lists API methods and the events they fire when called.

APIEvent(s) Fired



accounts.finalizeRegistrationaccountRegistered | accountUpdated | subscriptionUpdated
accounts.linkAccountsaccountUpdated | accountMerged
accounts.loginaccountLoggedIn | accountLockedOut | accountMerged (in link account scenario)
accounts.notifyLogin accountUpdated | accountLoggedIn | accountRegistered | accountCreated (for new site users) | accountMerged (in link account scenario) | accountProgressed (if progressed from lite account)

accountCreated | accountRegistered | accountLoggedIn* | subscriptionUpdated | accountProgressed (if progressed from lite account)

* If the site policy requires email verification, accountLoggedIn will not fire following accounts.register.



accountUpdated | subscriptionUpdated | accountProgressed (if progressed from lite account)
accounts.resetSitePreferencessitePreferencesReset | accountUpdated
SAML login accountCreated | accountRegistered | accountLoggedIn
socialize.getTokenaccountProgressed (if progressed from lite account)
socialize.notifyLogin accountUpdated | accountLoggedIn | accountRegistered | accountCreated (for new site users) | accountMerged (in link account scenario) | accountProgressed (if progressed from lite account)
socialize.notifyRegistrationaccountRegistered | accountUpdated | accountMerged (in link account scenario) | accountUidChanged
socialize.setUIDaccountUpdated, accountUidChanged
Social Login (if new user)accountCreated | accountRegistered | accountLoggedIn | accountUpdated
Facebook Social SyncaccountUpdated (The event is fired when the following fields are updated via Social Sync - birthday, books, education, email, first_name, hometown, last_name, likes, link, locale, location, movies, music, name, relationship_status,  religion,  verified, timezone and work).

TLS Protocols

HTTPS webhooks support TLS protocols 1.1 and 1.2. 

IP Whitelisting

Webhooks requires that your notificationURL is accessible to Gigya's systems. We realize that you might not want this URL public, for security reasons.

To allow Webhooks to function properly, you should make exceptions in your security system to allow traffic from Gigya. Generally, all Gigya addresses should be whitelisted, and they can be found here. Webhooks user the "NAT IP" addresses.


Additional Information







  • No labels