Getting started with Okta Event Hooks (webhooks)

hi everyone and welcome to this tutorial on octa event hooks so what are we going to be doing in this tutorial let me just pull up what i have written down in my visual studio code so we're going to be doing a short tutorial using octa event hooks we're going to be locally receiving event hooks from octa on our machine and these are the series of steps we're going to take to do that we're going to run a local api we need an api for octa to call so we're going to run a local api then we use the udex cli to generate a web book url that is where our event book is going to point to it's going to point to an https url generated using the cli this will be a publicly accessible url and it will point to our local running api so we're going to test the event hooks we're going to send events from octa and we're going to receive them on our local machine and then we inspect the result so let's get right into that the first thing to do is to run a local api now you can already have a local api running you can run in an api written in any language of your choice the main thing you have to take note of is that of two things you first have to have an end point that the octa event books are going to call and you also need to know the port that the application is going to be running for this exercise i'm going to be using a sample node.js api that is available on the hook deck ripple so you can go to this uh github page and clone this api it's a very simple api just has a couple of endpoints for receiving web hooks so i already have it cloned let's go back to visual studio code i already have it cloned and if we scroll down a little bit on the routes page you can see an endpoint here is a post endpoint and it is named octa-webhooks dash endpoint this is the end point with which i'm going to be receiving my octa event hooks you can give this endpoint any name you want but make sure you follow up in the tutorial when we are entering this endpoint you make sure that you substitute it with your own endpoint so we have uh our route endpoint to receive our event hooks and note is a post endpoint because octa event oaks are sent the http requests for octa event books are sent as post requests so it has to be a post request so um next what do we do next let's look at our list we generate a web book url but first we need to run the local api so i'm just going to go to my cli yeah my cli i'm already at the root of my project if i type pwd to pull that up you see i'm inside the project so what i'm just going to do here is run npm start this will automatically start my server i need to start at port one three three seven make sure you note this spot your api might be running on a different part but just make sure that you note the parts for the next step in the process so the next step is to generate a web book url yeah generate a web url using the cli you need to install the hook deck cli to be able to use the tool so you can simply just google hook deck cli and the first result should definitely pull up information on how to install the cli and how to use it on your system it's actually available for mac os the value for windows and is also available for linux and you can also run it in the docker container if you want to or you prefer that once you have the xli installed let's go back to our terminal thumbnail terminal yeah so i'm going to open a new tab this can be done anywhere you don't actually have to be at the root of the project but you can run this uh command anywhere you run the command hook deck listen then you supply the port that your application is running for me my application is running at port one two three seven so i supply port one two three seven now hit enter this is going to bring up an interactive cli session instead of not selected source i've already created some connections here and i've already created one for octa first try but i'm just going to create a new one because you most likely don't have any connections so i'm just going to click create a new connection and the next question is ask me is what should be the new source label i'm going to say octa events you can actually give this any name you want just make sure that there are no spaces in between octa events yeah that's good what part should the web looks before that too now this is your endpoint this is asked to be the relative uh url to your endpoint that's for local debugging definitely so i'm just going to come here and copy this octa dash workbooks endpoint eventually actually uh in octazone implementation of web books so you can just use the name interchangeably but octa prefers to call it event works so i'm just going to paste that here this is going to be my endpoint octa web box endpoint just go to hit enter to keep that in connection label you can give this a name you want i'm just going to name it my server my server that should be enough so my server so as you can see after hitting enter hook deck gives me a web book url and i have a web url for my octa events uh connection so this is the web carrier that we're going to be using for our event hooks let me go back to vs code and see if i'm still in sync with my steps yeah we've generated a web url that's good now we need to register for an event took on octa so make sure that you're on the octa admin page in doctor admin page then you go to workflow on the left hand side menu and click on event hooks let's check again on the cli session as you can see the cls is ready this cli session is actually active and it's saying that it's ready to receive connections so you have to leave this open you have to leave this open because when octa starts to send event hooks they're going to be registered here so going back to octa's admin page on the event books page to create a new event hook see the create event hook button and click that so we get a dialog that prompts us to add event hook and event to endpoint first we are told to put in a name just going to put a simple descriptive name let's say my test my octa test event hook that should be fine in the url field simply paste in the web book url that we generated using the ogdex cli next we have an authentication field and an authentication secret now for security purpose you might want to verify that your web books or event books are actually coming from octa octa gives you the opportunity to add a a header field you can give this a name you want and you pass in something like an api token or an api key you pass an api key into it this is something you supply yourself so i can say i want this in an authorization header and i want my api key to be one two three four five six seven eight whatever that whatever you want that to be one two four five six seven eight so um this would allow you to receive the header with each event request and verify it to ensure that this is actually coming from octa as you have defined now these are things that you're going to define yourself octa is not going to define it for you you have to provide the name of the header and also the secret that you want to be passed in the header and you also do the verification on your own end uh for this practice we won't need that this is just a demo so we just want to see stuff work so next custom header fields you can add custom edit fields um we're going to be doing that but feel free to do that in case your use case requires it then we click into the subscribe to events field and select an event to subscribe for you can select multiple events for this demo we'll just look for the user created event that should be enough octa allows you to subscribe for more than one event and you can have data for more than one event sent in one single request everything looks good so i'm just going to click save and continue and then yeah we get this verify endpoint ownership dialog box now octa has or octa requires um a one-time verification request to be sent to your endpoint just to confirm that you own the endpoint so is you kind of you you need to provide a get route handler for the same endpoint that's the endpoint that you just submitted you have to provide a get version of that endpoint the endpoint that octa is going to eventually call for the event itself has to be a post throughout handler but you have to provide a get route handler for octa to verify the endpoint and octa has uh some information as to what it wants you to do to verify this endpoint you can click on this link to get information about that but basically what happens is that octa sends a special header to your endpoint and you are to receive a value from that error this is the end point uh this is the error rather is x octa verification challenge that's the header so octa sends a value in this header and you have to return that value to octa in your response body by specifying it in a verification parameter so you can come to this page to get more information about that but that's basically how octa confirms that you own the end point lucky for us hook deck already takes care of this hook deck seamlessly integrates with octa so the webinar qrl that hook deck just generated for us is capable of verifying this by itself so simply click verify as you can see endpoint ownership successfully verified we didn't have to do anything because uktec has taken care of that for us so now we are registered for our event hook let's look at what is next go back to visual studio code okay so we have registered for an event to call octa we registered for the user created event hook so now we can test our event we can test it how do we do that do we have to simulate the question of the user in octa nope nope we don't have to because octa actually gives us the opportunity to send the test webhook for the event that we just created right now we're on the event page the my octa test event hook that we just created and all you need to do to to send a test web hook is to pick an event type from this drop down so you just select and we have user created already which is the only event that we subscribed for octo automatically fills this system log event stuff right here you don't need to worry about that and you get a preview of what the request body is going to look like so you can actually inspect this before sending it to see if it actually contains the data that you expect to fire the event hook request just click on the delivery request button down here once that's successful you get a request delivery successful message now let's confirm that we are receiving the event hook on our local machine and to do that we go to the cli so just notice i've not been able to get my book because it's failing for some reason oh my server is down okay i think my during this tutorial my um cli kind of went down so i had to restart it i forgot that my server was down so i'm just going to run mpm start again so that can be one of the issues where that can cause your connections to fail you just have to check on your server to make sure that it's still running okay my server is back up let's try that again click delivery request once again and now we should have positive response good status code 200 so we have status quo 200 we're successfully receiving the event hook is a post request as expected and it is landing on the octa dash web books dash endpoint endpoint yeah now we have been able to successfully get our event hooks landing in our local machine now let's inspect the results if you check aside this status code and the request method and we have the endpoint we also have an item here that is a url is a url and what this gives us is a page where we can view the details of this event that we just received so copy the url and go to your browser let's open a new tab and just stick that in okay okay okay loading up and here we get taken to an event page where we can inspect all the information regarding the event that we just received on our local machine you can see details of the connection is from the octa events connection to my server um this is the time i'm receiving the event and here we have another section down here we have headers you can see the octa request id this id is unique for every request and you can use it to actually verify if you have received a particular event request before so that you don't process it a second time just to basically identity to make sure that your end point is important so you can get all your editors here and um down here we have the body which is where you're going to be most interested the body we have the uh some details here just general details around the event that has been sent but the most important item in this body is the data and the event array inside data this is where octa puts information about all the event hooks that it's sending now this is an array you'd expect an object to just represent the object to just represent the event that you're receiving but octa sends it in an array because as i said earlier octa gives you the ability to receive more than one event in a single event request so we have all the event objects inside this array we only subscribe for one which is the user created and that's what we fired so we have just one entry in this array and we have all the properties for the data received in that event hook request so this is most likely most of the time this is the data you're going to be interested in so we've been able to set up our system to receive event hooks from octa on our local machine and now we are inspecting the request we can see all the details well formatted easy to visualize and easy to inspect that's one of the wonderful things that you dex cli gives us some of the benefits of the xli is the fact that you can actually retry the event so you can click this retry button to retry this event maybe at first you got the event on your system and your code is not responding the way you want it to so you fix that you fix that bug in your code and you want to run the test again so you just click with try and the request is retried for you to once again inspect your response to the event hook another thing you can do is bookmark if this event is a special one if you need to reference it later you can have a bookmark say my special octa oak so you can just add a bookmark here and um this event gets booked back as you can see it's now marked you can see all your events here on the events page you can click that and um this is the one that's errored and this was a successful one as you can see we have one attempt we can retry this if we will try it click this retire button we're going to get second attempt is processing but as you can see you can actually drill down to all these attempts you can click them one by one to view the data the data appears here on the right hand side so you can click it attempt to view the data contained in it so that's our tutorial on working with octa event hooks if you have enjoyed the video please like it and subscribe to the channel for more awesome content on webhooks

Channel: Hookdeck

Views: 351

Keywords:

Id: yIkgIhOUdug

Length: 16min 38sec (998 seconds)

Published: Mon Jul 12 2021