Description |
Registers the URL and settings associated with my Webhook. The Event Hub will push Events to the specified URL.
|
|
URL Structure |
|
|
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"
})
}
};
|
|