Register Webhook

 

Description

Registers the URL and settings associated with my Webhook. The Event Hub will push Events to the specified URL.
URL Structure
{Base URL}/webhooks
HTTP Method POST  
Authentication Required  
Request Headers none
Parameters none  
Request Body 
<webhook xmlns="http://ws.byu.edu/namespace/event-hub/v1">
   <identity_id/>       --leave blank 
                        -- unless acting as administrator
   <identity_name/>     --leave blank 
   <endpoint/>          --required
   <push_option/>       --required "Push Message" or "Push Alert"
   <security_option/>   --optional Specify "None" for no security or leave blank for HMAC auth
   <security_key/>      -- generated by EventHub
   <content_type/>      -- required "application/json" 
                        --   or "application/xml"
</webhook>
 
<webhook xmlns="http://ws.byu.edu/namespace/event-hub/v1">
   <identity_id/>
   <identity_name/>
   <endpoint>https://hr.byu.edu/example/endpoint</endpoint>
   <push_option>Push Message</push_option>
   <security_key/>
   <content_type>application/xml</content_type>
 </webhook>
 
{
  "webhook": {
    "endpoint": "https://hr.byu.edu/example/endpoint",
    "push_option": "Push Message",
	"content_type": "application/json"
  }
}
Returns 
<webhook xmlns="http://ws.byu.edu/namespace/event-hub/v1">
   <identity_id/>       --from authentication or request
   <identity_name/>     --retrieved from PRO
   <endpoint/>          --from request
   <push_option/>       --from request 
   <security_option/>   --from request
   <security_key/>      --supplied by Event Hub
   <content_type/>      --from request
</webhook>
 
<webhook xmlns="http://ws.byu.edu/namespace/event-hub/v1">
   <identity_id>388211692</identity_id>
   <identity_name>HR Benefits System</identity_name>
   <endpoint>https://hr.byu.edu/example/endpoint</endpoint>
   <push_option>Push Message</push_option>
   <security_option>HMAC</security_option>
   <security_key>bce718b80c2d4952a4611861cdfad51d</security_key>
   <content_type>application/json</content_type>
</webhook>
 
{
  "webhook": {
    "identity_id": "388211692",
    "identity_name": "HR Benefits System",
    "endpoint": "https://hr.byu.edu/example/endpoint",
    "push_option": "Push Message",
    "security_option": "HMAC",
    "security_key": "bce718b80c2d4952a4611861cdfad51d",
    "content_type": "application/json"
  }
} 
VERSION 3
{
  "webhook": {
    "address": "https://hr.byu.edu/example/endpoint",
    "port" : 80
    "push_option": "Push Message",
	"acknowledge": "true" or "false"
  }
}

Errors
Return Code Additional Explanation
403 Only Event Hub Administrators or Entity Administrators may register a Webhook for another Entity.
404 Webhook already defined.
409 Invalid eca_identity_id
409 Invalid Push Option requested - select 'Push Message' or 'Push Alert'
409 Invalid Security Option requested - only 'HMAC' or 'None' is currently supported
409 Invalid Content Type requested - only 'application/json' and 'application/xml' supported 
<fault_message xmlns="http://ws.byu.edu/namespace/event-hub/v1">
  <return_code/>   -- http return code
  <explanation/>   -- see the table above
  <error_data/>    -- from request
</fault_message>
 
<fault_message xmlns="http://ws.byu.edu/namespace/event-hub/v1">
   <return_code>409</return_code>
   <explanation>
      Invalid Push Option requested - select 'Push Message' or 'Push Alert'
   </explanation>
   <error_data>Push Notification</error_data>
</fault_message>
 
{
  "fault_message": {
    "return_code": "400",
    "explanation": 
      "Invalid Push Option requested - select 'Push Message' or 'Push Alert'",
    "error_data": "Push Notification"
 }
}
Notes

In order to define a Webhook, you must authenticate as:

  • An Event Hub administrator (supply the ECA Identity ID),
  • The ECA for the Push Client End Point, or
  • An administrator of the ECA (supply the ECA Identity ID). (future implementation)
  

 

When an event is pushed to your webhook and you've specified "HMAC" authentication, the request will contain a "X-Byu-Eventhub-Hmac-Md5" header that is generated using the webhook's "security_key" along with the data sent in the request.

You can then verify that the payload DID INDEED come from the EventHub by computing the hexadecimal MD5 HMAC digest of the message using your security_key and the message payload and compare it to the header field.

If they match, you can be sure that the event was sent from the EventHub and the data has not been compromised.

More on HMAC authentication.

 

For example, if your webhook was written in PHP and you wanted to verify a request, you could do it like this, using PHP's built-in hash_hmac() function:

<?php
// Where $body is the POST body sent to your webhook, $hmac_header is
// the value of the 'X-Byu-Eventhub-Hmac-Md5' header, and $security_key is your
// wehook's security key.
$calculated_hmac = hash_hmac('md5', $body, $security_key);
if ($calculated_hmac == $hmac_header) {
    // Verified...hooray!
} else {
    // Uh oh...
}
?>

 

Here is another example in node.js for an AWS Lambda function:

"use strict";
const crypto = require('crypto');

exports.handler = function(event, context, callback) {

  console.log("event: ",event);
  console.log("context: ",context);

  let header_X_Byu_Eventhub_Hmac_Md5 = event.headers['X-BYU-EventHub-Hmac-MD5'];

  console.log("X-BYU-EventHub-Hmac-MD5 header: ",header_X_Byu_Eventhub_Hmac_Md5);
  console.log("process.env.SECURITY_KEY: ",process.env.SECURITY_KEY);

  let digest = crypto.createHmac('md5', process.env.SECURITY_KEY).update(event.body).digest('hex');
  let isValid = digest === header_X_Byu_Eventhub_Hmac_Md5;
  if(isValid) {
    callback(null,{
      statusCode: 200,
      headers: {},
      body: "Success"
    })
  }
  else {
    callback(null,{
      statusCode: 500,
      headers: {},
      body: "Did not validate"
    })
  }
};