Edit this doc

Using Webhooks

The OrderCloud API supports user-defined HTTP callbacks, known as webhooks. Webhooks are easy to register for your entire organization or on an application specific level. You can choose exactly which OrderCloud API endpoints will trigger your hook, the roles to be passed onto the configured Base URL, and any additional configuration data OrderCloud may need to authenticate into 3rd party systems.

Webhooks can only be triggered by OrderCloud endpoints that write to the database (POST/PUT/PATCH/DELETE). The request body sent to the OrderCloud endpoint (if any) will be passed along to the webhooks that use it.

One way to configure your Webhook is through Zapier. Zapier is a UI that connects apps and helps you configure workflows. It is a very user-friendly way to get started with Webhooks. Here's how to set up a "Zap":

Create the Hook URL

First of all, if you don't have one already, go ahead and register for a Zapier account. It's free and the trial lasts 14 days - plenty of time to explore and play! Zapier is self-described as "... your Swiss Army knife for the web. It's one of those tools you can constantly come back to for automating mindless tasks". With that in mind, let's make a simple Zap to use in our OrderCloud webhook.

Once logged in to your Zapier account, click the "Make a Zap" button at the top of the page. Next, search for "Webhooks for Zapier," and click the "Catch Hook" radio button. Click continue, and continue again (we won't pick off a child key for this example). This will produce a URL that we will register in the OrderCloud dashboard. Copy this URL for the next step.

Register Your Hook with OrderCloud

Back in the OrderCloud Console create a new webhook

create_webhook

Webhook Info

Name, Description and Secret can be whatever you like. Use the recently copied Zap URL for Url.

Trigger Events

This tells OrderCloud to trigger our Zap whenever the route(s) of choice are called from this application. For this example, we'll be triggering the "Create a new user" route. This means that everytime a user is created, we'll use our webhook to follow that up with another action. To let Zapier know this is our intention, simply select Users from the drop down list as the Resource and Create New User as the endpoint.

Elevated Roles

Elevated roles are a used for passing along an access_token with higher permissions than the client that triggered the webhook. For instance, if the authenticated user only had the UserAdmin role but our Zap needs to list Categories and perform some other action, we would add CategoryReader to the elevated claims. For this example we will choose FullAccess here and save the webhook.

Test Your Webhook

The Zapier dashboard will prompt us to test our webhook by calling the URL that was generated in Step 1. We will do one better and test the OrderCloud webhook system at the same time. Return to Zapier and click "okay, I did this" to start the test. Once the loading indicator pops up, open the API Console with the application that has your webhook and Create a New User. (remember this is the route that we configured Zapier to listen to in Step 1.)

If everything has been configured correctly, we should be able to create a new User and see that triggered in Zapier. Shortly after you create a user on OrderCloud, the Zapier dashboard should notify you that your test was successful. Zapier will provide some guidance if the Test fails, you may have to reattempt creating a new user in the API Console if this happens.

If all goes well we will have caught the Create New User event from our OrderCloud application!

Perform an OrderCloud Action from Zapier

Now we are able to set up an "Action" step. To keep it simple, let's use our Zap to update the newly created user with a different last name. Once again we will choose "Webhooks by Zapier". Because this is an Action step, we are presented with different options. Click "show more options", select Custom Request, and hit continue.

Here's where it gets interesting. Zapier will use your last successful test data to help you model your action template. Set the HTTP method to PATCH. The URL will use data from the original request (Step 1: Catch Hook) for route parameters. Start by typing "https://api.ordercloud.io/v1/buyers/" - now, click the icon to the right of the input and you should be able to find an option for Route Params Buyer ID. Continue your URL with "/users/" - now find Request Body ID in the dropdown on the right. This is the ID of the user that was created on OrderCloud during our test in Step 2.

Hopefully you're beginning to see just how useful Zapier can be when working with OrderCloud webhooks. Our URL is now set up to PATCH the user created in Step 1: Catch Hook. But what will we PATCH it with? Skip down to the Data text box in the custom request form. This is where we can enter the request body for our action. Write in a simple request body:

{
  "LastName": "TestLastName"
}

One last piece of configuration. We need to provide Zapier an access_token it can use to make the request. Under Headers enter in a key of Authorization and a value of "Bearer " (don't forget the space). Similar to how we set up our URL, click the dropdown on the right of the value field and find User Token. This will pass through the generated token which has our Elevated Claims (FullAccess) from earlier. Let's also add a Content-Type header of application/json.

Finally, hit "Continue" and verify the request looks like this:

Method
PATCH

URL
https://api.OrderCloud/v1/buyers/SAZBUYER/users/test

Data
{
  "LastName":"TestLastName"
}

Unflatten
yes

Headers
application/json
Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Test the Action Step

Finalize your Zap in the Zapier interface (one final test for the Action step), turn it on, and try creating another user in the API Console. Shortly after, GET the user you just created. If everything worked correctly, their last name should now read "TestLastName".

Conclusion

Congratulations! You've successfully created a Zap-based OrderCloud webhook that can alter data in the origin application.