Published by Jake Hookom
April 4th, 2021
The OrderCloud API supports user-defined HTTP callbacks, known as webhooks. Webhooks are easy to register for your entire marketplace 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.
There are two types of webhooks you can use with OrderCloud:
Webhooks can be written in any language to receive an HTTPS request, but we recommend you use OrderCloud Catalyst to ease creation of strongly typed webhooks in C# (which also includes examples).
To better understand what OrderCloud sends in webhooks, here is an update to a buyer v1/buyers/buyer_10
:
{
"Route": "v1/buyers/{buyerID}",
"RouteParams": {
"buyerID": "buyer_10"
},
"Verb": "PUT",
"Date": "2021-04-04T19:41:39.6504645+00:00",
"LogID": "71ce120a-17d5-4833-89f6-4f9a33ddd42f",
"UserToken": "...",
"Request": {
"Body": {
"Active": true,
"Name": "New Name Updated",
"xp": {
"segment": "Foo"
}
},
"Headers": null
},
"Response": {
"Body": {},
"Headers": null
},
"ConfigData": {
"config_key": "config_value"
}
}
OrderCloud will optionally pass an x-oc-hash
header which is a fingerprint for the request, based on a secret you can optionally define when you register your webhook in OrderCloud. You may want to do this in order to verify that any request sent to your webhook can be trusted and is actually from OrderCloud.
Verifying this fingerprint happens automatically when you use OrderCloud Catalyst, but you can do this yourself with a SHA256
using your registered secret, and hashing the passed request and comparing the Base64
value to the value passed in the x-oc-hash
header.
Only applicable for pre-webhooks, you return a basic JSON structure on if you should proceed
true or false, and an optional body
which can be any JSON object or literal value.
{
"proceed": false,
"body": {
"customMessage": "Not a Valid Address",
"suggestions": [
...
]
}
}
If you set proceed
to false
, then an error message will be sent back to the original caller and includes the body
data you provided for the client to act upon or use.
Back in the OrderCloud Console create a new webhook
x-oc-hash
where OrderCloud will use this secret to generate a fingerprint you can validate againstWebhooks will only fire for the API Clients you specify. This is ideal when you may have multiple API clients setup, representing different store fronts and behavior. If you want the webhook to fire for all your different API clients, then simply check each one in the portal UI.
These are optional key value pairs you can setup and will be passed with each request. Think in terms of shared plugins where you may want to pass other registration or account information to a 3rd party tax or shipping service.
This is where you register one or more operations you want to attach your webhook to in OrderCloud. Example, if you want to listen for all updates to Buyers, you would want to register POST, DELETE, PATCH, and PUT
Elevated roles relay an access_token
with higher permissions than the client that triggered the webhook. For example, if an authenticated user only had the UserAdmin role but our webhook needed to list Categories and perform some other action, we would add CategoryReader to the ElevatedRoles
. For this example we will choose FullAccess here and save the webhook.
The following example registers a webhook for all of the Buyer endpoints
{
"ID": "...",
"Name": "sample-webhook",
"Description": "Sample Description",
"Url": "https://.../mywebhook",
"HashKey": "...",
"ElevatedRoles": [
"BuyerAdmin"
],
"ConfigData": {
"config_key": "config_value"
},
"BeforeProcessRequest": true,
"ApiClientIDs": [
"...."
],
"WebhookRoutes": [
{
"Route": "v1/buyers",
"Verb": "POST"
},
{
"Route": "v1/buyers/{buyerID}",
"Verb": "DELETE"
},
{
"Route": "v1/buyers/{buyerID}",
"Verb": "PATCH"
},
{
"Route": "v1/buyers/{buyerID}",
"Verb": "PUT"
}
]
}
3rd parties looking to create reusable plugins to replicate data or validate data written to OrderCloud could offer URLs where support for multiple OrderCloud customers or organizations could be based on the following:
x-oc-hash
headerDeployment of these services could either be through GitHub as integration code the customer could deploy themselves and freely modify to map extended properties (XP) or other fields they may map differently per instance, or as a global service endpoint that you host and OrderCloud customers simply point at and use.
In both cases, the deployment would ideally be a serverless function which keeps cost and maintenance down to nothing to provide reusable integrations.