Webhooks

Skip to end of metadata
Go to start of metadata

Introduction

Gigya webhooks push notifications of account events to your server. 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.

Supported Events

The following events are supported:

  • Account created - fired when a new account record is actually created in Gigya's database.
  • 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.

Subscribing to Events

Perform the following for each site in which you want to use webhooks. Note that for site groups, you essentially define the webhooks for only one site to activate it for the entire group. 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. 
    3. 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. 
    4. Select the events to which this webhook is subscribed. 
    5. Click Create.

Notes

  • 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.

Retrieving Webhook Data

Use the accounts.webhooks.getAll API to retrieve all currently defined webhooks. 

Notification Format

The notification consists of an HTTP POST request containing a Notification Object in the body.

Notification Object Members

Field NameTypeDescription
eventsArray

An array of JSON objects, each one consisting of:

  • type - The event type. Possible values are:
    • accountCreated
    • accountRegistered
    • accountUpdated
    • accountDeleted
    • accountLoggedIn
  • 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.
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

{
	"events":[
	{
         "type":"accountRegistered",
         "id":"b3e95b42-5788-49a7-842a-90c0f183d653",
         "timestamp":1450011476,
         "data":{
            "uid":"9465ce7ee5d741209b635f7ad8137ae3"
             }
	},	
	{
		 "type":"accountCreated", 
		 "id":"f3e97c42-8758-45a7-248b-09a4ed381356",
		 "timestamp": 1448716764,
		 "data":{
			"uid":"9465ce7ee5d741209b635f7ad81374ae"
			 }
		}
	], 
	"nonce":"8693aa10-9c75-48c9-a959-6ef1ae2b6b54",
    "timestamp":1450011477
}

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.

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 flight, notifications contain a signature in the X-Gigya-HMAC-SHA1 header.

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

Handling Notifications

Verifying the Hash

It's important to verify the hash passed in the X-Gigya-HMAC-SHA1 header to ensure the authenticity of the notification. To verify the hash:

  1. Create an HMAC-SHA1 hash of the JSON payload using a User Secret or Partner Secret as the key. For more information on signing notifications using a User Secret, see accounts.webhooks.set.
  2. Compare your hash to the one received in the X-Gigya-HMAC-SHA1 header.

If the hashes match, the notification is considered valid.

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). 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 accounts.search 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.

 

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.

<?php
 
// 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']; 
 
 
// 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.
    http_response_code(200);
 
} else {
   
    // The hash isn't good, respond non-OK. Gigya will try to resend this notification at progressively longer intervals.
    http_response_code(400);
}
 

?>

 

API Event Mapping

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

APIEvent(s) Fired
accounts.deleteAccountaccountDeleted
accounts.finalizeRegistrationaccountRegistered | accountUpdated
accounts.linkAccountsaccountUpdated
accounts.loginaccountLoggedIn
accounts.notifyLogin accountUpdated | accountLoggedIn | accountRegistered | accountCreated (for new site users)
accounts.register

accountCreated | accountRegistered | accountLoggedIn*

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

accounts.setAccountInfoaccountUpdated
accounts.setPasswordaccountUpdated
accounts.verifyEmailaccountUpdated
SAML login accountCreated | accountRegistered | accountLoggedIn
socialize.notifyLogin accountUpdated | accountLoggedIn | accountRegistered | accountCreated (for new site users)
socialize.notifyRegistrationaccountRegistered | accountUpdated
socialize.removeConnectionaccountUpdated
socialize.setUIDaccountUpdated
socialize.setUserInfoaccountUpdated
Social Login (if new user)accountCreated | accountRegistered | accountLoggedIn
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.  

Additional Information

accounts.webhooks.set

accounts.webhooks.getAll

accounts.webhooks.delete

 

 

 

  • No labels